Overview
ID5’s Matching File-Transfer 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.
- You will upload a file containing a list of your UIDs to the S3 bucket in the appropriate
inboxdirectory - ID5 will process the file and return to the
outboxin the S3 bucket a new file with a list of your match partner’s UIDs for every user we could match
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 on ID5's side 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 into 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.
The above files will be processed and saved in
File Format
Inbox
| Column | Type | Description |
|---|---|---|
| UID | String | Your 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 |
|---|---|---|
| UID | String | Match 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 |.
| Column | Type | Description |
|---|---|---|
| UID | String | Your UID for this user |
| UID | String | Match Partner's UID for this user |
Enabling this setting has a commercial impact, so please speak to your Account Manager if you'd like to discuss this integration method.
Example Files
Inbox Sample
Outbox Sample
Matched Users Only
Pairs Output
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.