Inbound Data File Contents: Syntax, Invalid Characters, Variables, and Examples
Required fields, syntax, and rules you should follow when formatting an inbound trait data file.
File Content Syntax
Fields in the inbound data file must appear in the order shown below. In this example, the <
>
symbols have been added to help separate each element visually. You do not need to include these in your data file.
<user ID><TAB><trait ID>,<trait ID>,<trait ID>,...
For other accepted file content formats, see Custom Partner Integrations.
code language-none |
---|
|
File Variables Defined
The table lists and defines the variables used in a properly formatted inbound data file. Italics indicates a variable placeholder.
User ID
A User ID can be:
- A unique user ID assigned by Audience Manager ( Audience Manager UUID).
- A unique user ID assigned in your CRM system ( DPUUID, in Audience Manager).
- A mobile Android or iOS device ID in its original, unmodified form as exposed by the mobile operating system.
For mobile IDs:
- IDFA format: IDs must be upper case and not hashed. For example,
6D92078A-8246-4BA4-AE5B-76104861E7DC
- Android format: IDs must be lower case and not hashed. For example,
97987bca-ae59-4c7d-94ba-ee4f19ab8c21
TAB
trait ID
The Audience Manager trait ID. We ask that you include only onboarded traits in inbound data files. We do not process any other trait types in the inbound data transfer.
Note: The Trait ID can be found by using the GET method that returns details about all your traits. For more information, see Trait API Methods.
Formatting Trait IDs
The following table describes the prefixes that identify trait names or IDs in an inbound data file. See the sample files for examples.
d_sid=
d_sid
prefix tells our system that the ID is an Audience Manager trait ID. This is the same ID that's shown in the user interface. You can also return trait IDs with the API GET
method. See Trait API Methods.d_unsid=
Data prefixed with d_unsid
removes users from that trait. The d_unsid
prefix is ignored in an overwrite
file.
The d_unsid=
prefix tells our system that the ID is an Audience Manager trait ID. This is the same ID that's shown in the user interface. You can also return trait IDs with the API GET
method. See Trait API Methods.
ic=
Trait ruleslet you set criteria for trait qualification. If you format a trait rule as ic == trait ID
, you can send in traits in a simple comma formatted list.
For example, say you create these 3 trait rules:
ic == "123"
ic == "456"
ic == "789"
These traits are associated with the ic
key. This lets you create a simpler trait list in the data file. And, you do not need to include the ic
prefix. As a result, the contents of your data file could look like this:
user ID <TAB> 123,456,789
Trait data can be formatted as key-value pairs using alphanumeric strings. There are several ways of formatting key-value pairs, as shown below:
key = value
"key" = value
key = "value"
"key" = "value"
"age"="32"
, "gender"=m
, model = "pickup truck"
, product = tablet
are all examples of correctly formatted key-value pairs.
Invalid Characters in Trait IDs, User IDs and Key-Value Pairs
Trait IDs
Trait IDs consist only of numerical characters. We ask that you include only onboarded traits in inbound data files. We do not process any other trait types in the inbound data transfer.
User IDs
%3A
) or unencoded colon ( : ) symbol in DPUUIDs.Mobile device IDs must be strictly formatted as shown here:
- IDFA format: IDs must be upper case and not hashed. For example,
6D92078A-8246-4BA4-AE5B-76104861E7DC
- Android format: IDs must be lower case and not hashed. For example,
97987bca-ae59-4c7d-94ba-ee4f19ab8c21
Key-Value Pairs
Improperly formatted value names in a key-value pair also cause problems. Follow these rules when creating or naming the value in a key-value pair:
You can use the quote character in the key and in the value part of key-value pair, like so:
-
d_city = "New York", d_city = "San Francisco"
-
"d_city" = "New York", "d_city" = "San Francisco"
-product = camera
is interpreted as product = camera
.TAB
TAB
instead of empty values in key-value pairs. Only use TAB
to separate variables in the inbound data file.\n, \t
\n, \t
) in keys or in values.Data File Examples
d_sid
or d_unsid
This data file shows a user qualified for traits 24, 26, 27 and has been removed from trait 28 and 29.
59767559181262060060278870901087098252 d_sid=24,d_sid=26,d_sid=27,d_unsid=28,d_unsid=29
Note:
Instead of using d_unsid, you can also remove traits from user profiles by using the following syntax:
59767559181262060060278870901087098252 28:0, 29:0
59767559181262060060278870901087098252 28:-1, 29:-1
ic==
These traits have been added to a trait rule with the ic
prefix. As such, you can add them to the data file separated by commas as shown. A tab separates the UUID and the trait IDs. The ic
prefix is not required in the file.
Numeric IDs
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 30608,50354,50338,50352,30626
String IDs
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 ic=52,ic=55
This file data uses key-value pairs to pass in data to Audience Manager .
59767559181262060060278870901087098252 “gender”=”female”,“luxury_shopper”=”yes”
Download the sample data file if you need additional examples. The download file has a .overwrite
file extension. You can open it with a simple text editor.
Examples Matrix
The chart below shows examples of the correct way to format your Inbound files, depending on the type of IDs and the method by which you want to add traits to profiles.
Example 1
Use trait IDs to send trait qualification information for Audience Manager UUIDs.
59767559181262060060278870901087098252 <TAB> d_sid=24, d_sid=26, d_sid=27
Example 2
Use trait IDs to send trait disqualification information for Audience Manager UUIDs.
59767559181262060060278870901087098252 <TAB> d_unsid=24, d_unsid=26, d_unsid=27
or
59767559181262060060278870901087098252 <TAB> 24:0, 26:0, 27:0
or
59767559181262060060278870901087098252 <TAB> 24:-1, 26:-1, 27:-1
Example 3
Send in key-value pairs to add trait qualification information for Audience Manager UUIDs.
59767559181262060060278870901087098252 <TAB> product = tablet, product = phone
or
59767559181262060060278870901087098252 <TAB> "product" = "tablet", "product" = "phone"
Example 4
Use the ic
prefix to send trait qualification information for Audience Manager UUIDs.
59767559181262060060278870901087098252 <TAB> 30608,50354,50338,50352,30626
or
59767559181262060060278870901087098252 <TAB> ic=52,ic=55
Example 5
Use trait IDs to send trait qualification information for Android devices.
e4fe9bde-caa0-47b6-908d-ffba3fa184f2 <TAB> d_sid=24, d_sid=25, d_sid=26
Example 6
Use trait IDs to send trait disqualification information for Android devices.
e4fe9bde-caa0-47b6-908d-ffba3fa184f2 <TAB> d_unsid=24, d_unsid=25, d_unsid=26
or
e4fe9bde-caa0-47b6-908d-ffba3fa184f2 <TAB> 24:0, 26:0, 27:0
or
e4fe9bde-caa0-47b6-908d-ffba3fa184f2 <TAB> 24:-1, 26:-1, 27:-1
Example 7
Send in key-value pairs to add trait qualification information for Android devices.
e4fe9bde-caa0-47b6-908d-ffba3fa184f2 <TAB> product = tablet, product = phone
or
e4fe9bde-caa0-47b6-908d-ffba3fa184f2 <TAB> "product" = "tablet", "product" = "phone"
Example 8
Use the ic
prefix to send trait qualification information for Android devices.
e4fe9bde-caa0-47b6-908d-ffba3fa184f2 <TAB> 30608,50354,50338,50352,30626
or
e4fe9bde-caa0-47b6-908d-ffba3fa184f2 <TAB> ic=52,ic=55
Example 9
Use trait IDs to send trait qualification information for iOS devices.
6D92078A-8246-4BA4-AE5B-76104861E7DC <TAB> d_sid=24, d_sid=25, d_sid=26
Example 10
Use trait IDs to send trait disqualification information for iOS devices.
6D92078A-8246-4BA4-AE5B-76104861E7DC <TAB> d_unsid=24, d_unsid=25, d_unsid=26
or
6D92078A-8246-4BA4-AE5B-76104861E7DC <TAB> 24:0, 26:0, 27:0
or
6D92078A-8246-4BA4-AE5B-76104861E7DC <TAB> 24:-1, 26:-1, 27:-1
Example 11
Send in key-value pairs to add trait qualification information for iOS devices.
6D92078A-8246-4BA4-AE5B-76104861E7DC <TAB> product = tablet, product = phone
or
6D92078A-8246-4BA4-AE5B-76104861E7DC <TAB> "product" = "tablet", "product" = "phone"
Example 12
Use the ic
prefix to send trait qualification information for iOS devices.
6D92078A-8246-4BA4-AE5B-76104861E7DC <TAB> 30608,50354,50338,50352,30626
or
6D92078A-8246-4BA4-AE5B-76104861E7DC <TAB> ic=52,ic=55
Example 13
Use trait IDs to send trait qualification information for DPUUIDs.
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 <TAB> d_sid=24, d_sid=25, d_sid=26
Example 14
Use trait IDs to send trait disqualification information for DPUUIDs.
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 <TAB> d_unsid=24, d_unsid=25, d_unsid=26
or
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 <TAB> 24:0, 26:0, 27:0
or
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 <TAB> 24:-1, 26:-1, 27:-1
Example 15
Send in key-value pairs to add trait qualification information for DPUUIDs.
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 <TAB> product = tablet, product = phone
or
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 <TAB> "product" = "tablet", "product" = "phone"
Example 16
Use the ic
prefix to send trait qualification information for DPUUIDs.
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 <TAB> 30608,50354,50338,50352,30626
or
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 <TAB> ic=52,ic=55