Skip to end of metadata
Go to start of metadata

Batch Segment Service - File Format

The Batch Segment Service provides the ability to upload segment data files in a variety of formats. See Examples below.

Speak with your account representative for assistance with configuring our system to accept your particular file format.

Format Overview

Each line of the file will specify a minimum of one UID (user ID) and one or more SEG blocks. The separators are configurable.

The following table describes the ordering of the blocks and separators that compose each line.

UID

Name

Type

Description

Example

UID

int

The Xandr user ID being added to, or removed from, a segment.

5727816213491965430

SEG Block

The SEG block describes the segment(s) to which the user is being added or removed, and will contain data such as the segment ID or a user-defined segment code.

Construct a SEG block as follows:

SEG_FIELD Block

The following tables list the possible values that may be included in the SEG_FIELD block. Where defaults exist, they will be applied unless otherwise specified. Note that each SEG block must be regular, meaning that it must have all fields that you have chosen to include. For example, if you have included the VALUE field but don't have a value for a particular user, you should use 0 as the value.

Name

Type

Description

Default

Example

SEG_ID

int

The Xandr segment ID.

This is generated by the system when the segment is created.

1234567890

SEG_CODE

string

A user-defined name for the segment. You may include SEG_CODE or SEG_ID but not both.

 

"18-35_autobuy"

EXPIRATION

int

The lifetime of the segment, starting at the value of TIMESTAMP. Specified in minutes. A value of 0 means that the user will expire in the segment after the maximum allowed 180 days; -1 means that the user will be removed from this segment.

The default value is specified on the segment level when the segment is created. If none exists there, your Batch Segment API configuration setting is used. Using this field will override the default.

1440

TIMESTAMP

int

The time at which you would like your segment to go into effect. A UNIX timestamp, down to the second. If a timestamp is submitted to greater specificity (down to the millisecond, for example) then the user will not be properly written to the segment upon upload.

The current time.

1278250469

VALUE

int

A numeric value you would like to assign to a segment.

 

310

Note: The maximum accepted value is 2147483647. (If a value above this is included, there may be behavior unpredictability such as the pixel fire not processing. Therefore, the user will not be added to the segment. Other times, it will be processed, however the value set will be much smaller than what was passed.)

MEMBER_ID

int

This field is required only if you use a SEG_CODE and upload other members' data in addition to your own.

The member_id.

958

DOMAIN

Name

Type

Description

DOMAIN

string

You may optionally specify a domain to associate with this user ID.

Separators

Read on for definitions of each separator type. Each separator must be different, except for SEPARATOR1 and SEPARATOR3, which may be identical (SEPARATOR2 and SEPARATOR4, cannot be identical). Each separator must be only 1 character in length. 

Disallowed characters

The following characters are not allowed as separators: [ ] ( ) { } $ \ / | ? * + -

SEPARATOR1

Separates the user ID from the segment list (or SEG block). There may be only one per line. Required.

SEPARATOR2

Separates segments within the segment list. There may be many per line, since multiple segments can be associated with a single UID. Required if there is more than one segment.

SEPARATOR3

Separates fields within each SEG block. If set, it must remain the same for each line of the file (except after SEPARATOR4). Required if there is more than one field within the SEG.

SEPARATOR4

The user will be removed from any segments appearing after this separator. Optional.

SEPARATOR5

The user will be added to the DOMAIN or looked up in the set designated directly after this separator. Optional.

Mobile Device ID Data Fields

In order to pass in device IDs from mobile devices, pass in SEPARATOR5 at the end of a line followed by one of the numbers shown in the table below; each number corresponds to a different mobile device identification scheme. This table assumes ^ is used as SEPARATOR5:

Separator and Number

Value

^3

idfa

^4

sha1udid

^5

md5udid

^7

openudid

^8aaid
^9windowsadid
^10rida

Note that the above value fields are case sensitive.

For more information about these values and the mobile device identification schemes they represent, see the Mobile Ad Call Reference (customer login required).

^6 sha1mac was deprecated as of May 7th, 2019. Do not use.

Examples

The following examples illustrate scenarios derived from real use cases.

The examples below show separator values that may differ from the ones that were set up in your initial batch segment configuration. Contact our Services team if you wish to update your configuration settings.

 

Example 1

A client is adding user 12345678900987654321 to segments 10000 and 10001 with an expiration time of 1440 (one day). The client is also removing user 12345678900987654321 from segments 10002 and 10003.

Field

Value

UID

Xandr user ID

SEPARATOR1

","

SEPARATOR2

";"

SEPARATOR3

":"

SEG_FIELD

[SEG_ID, EXPIRATION]

Example 2

A client is adding user 12345678900987654321 to segments with codes "auto_intender" and "nike_shopper" with the default expiration time. The client is also removing (using SEPARATOR4) user 12345678900987654321 from segments with codes "bicycle_intender" and "newbalance_shopper".

Field

Value

UID

Xandr user Id

SEPARATOR1

","

SEPARATOR2

";"

SEPARATOR4

"\t"  

SEG_FIELD

[SEG_CODE]

\t refers to the horizontal tab character. It moves the cursor a tab width. The example below is using \t to show where the space will appear.

Example 3

In the example, below, the client is adding user 12345678900987654321 to segments 10000 and 10001 with no expiration (which means the user will expire in the segment after the maximum allowed 180 days), and they are removing the user from segment 10002.

Field

Value

UID

Xandr user ID

SEPARATOR1

"\t"

SEPARATOR3

"\t"

SEG_FIELD

[TIMESTAMP, SEG_ID, VALUE, EXPIRATION]

\t refers to the horizontal tab character. It moves the cursor a tab width. The example below is using \t to show where the space will appear.

Example 4

A client is adding user "abcdefg" to segments 10000 and 10001 with an expiration time of 1440 (one day). The client is also adding user "abcdefg" to cross-segments 10002 and 10003.

This client is set as an XSEG member.

Field

Value

UID

Xandr user ID

SEPARATOR1

","

SEPARATOR2

";"

SEPARATOR3

":"

SEG_FIELD

[SEG_ID, EXPIRATION]

uses_external_uids

true

Example 5

A client is adding user 12345678900987654321 to segments with code "car_like" and "bike_like" with the default expiration time.

This client uses SEG_CODE and uploads under different member names.

Field

Value

UID

Xandr user ID

SEPARATOR1

","

SEPARATOR2

";"

SEPARATOR3

":"

SEPARATOR4

"\t"

SEG_FIELD

[MEMBER_ID, SEG_CODE]

\t refers to the horizontal tab character. It moves the cursor a tab width.

Example 6

A client is adding mobile user IDFA (ID for Advertisers) AEBE52E7-03EE-455A-B3C4-E57283966239 to segments 10000, 10001, 10002, 10003 for varying amounts of time, via the Batch Segment Service. This method often has low match rates on our platform because even if IDs are successfully submitted to our service, it doesn't mean that the device ID has actually been seen on our platform. Note separator 5 appended which designates the use of mobile identifiers. The value "3", designates Apple's IDFA value—other values can be found above in the Mobile Device ID Data Fields table.

Field

Value

IDFA

Apple ID for Advertisers

SEPARATOR1

","

SEPARATOR2

";"

SEPARATOR3

":"

SEPARATOR4

"\t"

SEPARATOR5

"^"

SEG_FIELD

[SEG_ID,EXPIRATION]

\t refers to the horizontal tab character. It moves the cursor a tab width.