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.

Contents:

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>,...
Note: We have a limit of 200 lines we can process for each user ID sent in the inbound data file. For example, if you send 300 lines for a user ID, the first 200 lines are kept and the additional 100 lines are discarded.

File Variables Defined

The table lists and defines the variables used in a properly formatted inbound data file. Italics indicates a variable placeholder.

Variable Description

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

Separate the User ID and trait IDs with a single tab delimiter.

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.

Prefix Description

d_sid=

The 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 rules let 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

Key-value pairs

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

ID Type Requirement

DPUUID

Do not use an encoded colon (%3A) or unencoded colon ( : ) symbol in DPUUIDs.

Mobile iOS (IDFA) or Android device ID

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:

Character Requirement

Quote character (")

Be careful when using the quote sign ( " ) in the value part of key-value pairs. The quote character must be escaped by using a double quote. Any of the examples below are accepted:

  • d _city = """New York"" or ""San Francisco"""

  • "d _city" = """New York"" or ""San Francisco"""

Dash character (-)

We ignore dash signs at the start of keys. For example, -product = camera is interpreted as product = camera.

TAB

Do not use TAB instead of empty values in key-value pairs. Only use TAB to separate variables in the inbound data file.

\n, \t

Do not use the new line or tab characters (\n, \t) in keys or in values.

Data File Examples

Data File Format Description and Example

With 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

With 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

Numeric IDs
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1	 30608,50354,50338,50352,30626

String IDs

String IDs
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1  ic=52,ic=55

With key-value pairs

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.

ID Type / Operation Use d_sid to add traits to a user profile Use d_unsid to remove traits from a user profile Send in key-value pairs to add traits to a user profile Use the ic prefix to add traits to a user profile
Audience Manager UUID

Example 1

Example 2

Example 3

Example 4

Google Advertising ID for Android Devices

Example 5

Example 6

Example 7

Example 8

Apple IDFA for iOS devices

Example 9

Example 10

Example 11

Example 12

Your own CRM ID (DPUUID)

Example 13

Example 14

Example 15

Example 16

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
or
59767559181262060060278870901087098252 <TAB> "product" = """tablet"""  or """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
or
e4fe9bde-caa0-47b6-908d-ffba3fa184f2 <TAB> "product" = """tablet""" or """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
or
6D92078A-8246-4BA4-AE5B-76104861E7DC <TAB> "product" = """tablet""" or """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
or
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1 <TAB> "product" = """tablet""" or """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