DMP Batch API

Revisions history

Basics

This document describes a generic way to upload DMP segments to Getintent DSP. The workflow is as follows:

• DMP uploads data through SFTP protocol on Getintent servers
  • Batch files with segments
  • Taxonomy files with segments meta information.
• DSP starts using segments data for targeting

Batch File name format

DMP data should be stored in txt.gz files and be named the following way:
[DMP ID].[DATE as yyyy-MM-dd_HH-mm-ss].[FILE ID].txt.gz
Where:

• [DMP ID] a string id assigned to DMP partner
• [DATE] date of file generation in specified format
• [FILE ID] unique file id

Example:
some_dmp. 2015-07-15_12-00-00.632a0017-bbda-4be7-a5fe-6a2478b65c89.txt.gz

Data format

The first line of file should be a header and will always be ignored. The further line should follow the syntax below:
[DMP USER ID]<tab>[DSP USER ID]<tab>[SEGMENTS TO ADD]<tab>[SEGMENTS TO REMOVE]
Where:

• [DMP USER ID] – DMP user id (could be empty)
• [DSP USER ID] – DSP user id (could be empty)
• [SEGMENTS TO ADD] – comma separated list of segments. Each segments should be an id or id:expiration timestamp (in UTC/milliseconds). Example "1,2,3" or "1,3,4: 1437061152368". If expiration time isn't given for segment a default expiration policy (configured per DMP) will be applied
• [SEGMENTS TO REMOVE] – comma separated list of segments

Notes:

• Only one of [DMP USER ID] or [DSP USER ID] should present (depends on which party is storing user matching tables)

User ID format

For display (desktop inventory format) [DMP USER ID] or [DSP USER ID] could be any string that doesn't contain ':' character.
For mobile DMP USER ID each user id should have a prefix

User matching flow

Getintent DSP can store user matching tables on their side but it's no recommended and should be done only in case it's the only option to integrate with DMP. The following matching cases are supported:

Taxonomy import

To keep segments list up to date recommended to use auto taxonomy import. Taxonomy file should be placed in the same location where batch file is placed. Taxonomy should have the same name prefix as batch file: [DMP ID].[DATE as yyyy-MM-dd_HH-mm-ss].[FILE ID].taxonomy.json

Taxonomy should be provided in json format and follow this format:

When no cost is provided then default pricing from DMP settings will be used.

[
    {
        "id": 1000,
        "name": "Mens 18-24",
        "cost_type": "RATE",
        "cost_value": 20,
        "currency": "USD",
        "advertisers": [
            1000,
            2000,
            3000
        ]
    },
    {
        "id": 1001,
        "name": "Mens 25-29",
        "cost_type": "FIX",
        "cost_value": "1",
        "currency": "USD",
        "advertisers": [
            1000,
            2000,
            3000
        ]
    }    
]