Data Partnership API¶

Overview¶

The Data Partnership API provides a curator-facing workspace where users can configure essential deal metadata, including deal IDs, campaign timeframe, cost type (CPM or percentage of media), cost value, and currency.

To integrate with Data Partnership API, use the following steps.

Get your API Access Token, which will be passed in the request header. If you do not have an API token or user account, use the steps outlined in the API Authorization section. If you have Read Only permissions you may only user GET queries. Request an API Account to access all API methods.
Retrieve or update deal details from Data Partnership API.

Creating Deals¶

To create a new deal, POST the details to Data Partnership API.

<!-- POST to this endpoint where the <id> is your data partner ID -->
/api/v1/data_partners/<id>/deals/

Request Body Example¶

{
  "deal_id": "dp_deal_partner_a_premium_2026",
  "fee_type": "cpm",
  "fee_amount": "2.50",
  "currency": "USD",
  "dsp": 101,
  "ssp": "ssp_a",
  "geo": ["US", "GB", "CA/ON"],
  "device_type": ["Phone", "Tablet", "PC"],
  "content_type": ["display", "video"],
  "domain": {
   "type": "allow",
   "values": ["example.com", "premium-site.com", "news-outlet.com"]
  },
  "bundle": {
   "type": "block",
   "values": ["com.example.app", "com.premium.app"]
  },
  "inventory_type": ["web", "in_app"],
  "iab_category": ["IAB1", "IAB1/IAB1-1", "IAB12"],
  "livestream": false,
  "start_date": "2026-06-01",
  "end_date": "2026-06-02",
  "custom_fields": {}
}

Note

For unconstrained geo, iab_category, domain, or bundle, please use null. Empty lists for geo and iab_category are rejected.

The API will respond with 201 Created.

Getting Deals List¶

To see the list of existing deals, GET the following endpoint:

<!-- GET this endpoint where the <id> is your data partner ID -->
/api/v1/data_partners/<id>/deals/

The API will respond with a paginated list of deals.

Paginated Item Example¶

{
  "id": 111,
  "deal_id": "deal_id",
  "dsp": 101,
  "ssp": "ssp_a",
  "fee_type": "cpm",
  "fee_amount": "2.50",
  "currency": "USD",
  "start_date": "2026-06-01",
  "end_date": "2026-10-01",
  "updated": "2026-06-01T15:03:00.000000Z"
}

Filtering Deals¶

The following filters are supported:

Filter	Type
query	string, matches `deal_id`
dsp	integer
ssp	string
page	integer
page_size	integer

Getting Deals Details¶

To get details of a particular deal, GET the following endpoint:

<!-- GET this endpoint where the <deal_pk> is the internal integer deal ID -->
/api/v1/data_partners/<id>/deals/<deal_pk>/

Deal Details Response Example¶

{
  "id": 111,
  "deal_id": "dp_deal_partner_a_premium_2026",
  "fee_type": "cpm",
  "fee_amount": "2.50",
  "currency": "USD",
  "dsp": 101,
  "ssp": "ssp_a",
  "geo": ["US", "GB", "CA/ON"],
  "device_type": ["Phone", "Tablet", "PC"],
  "content_type": ["display", "video"],
  "domain": {
   "type": "allow",
   "values": ["example.com", "premium-site.com", "news-outlet.com"]
  },
  "bundle": {
   "type": "block",
   "values": ["com.example.app", "com.premium.app"]
  },
  "inventory_type": ["web", "in_app"],
  "iab_category": ["IAB1", "IAB1/IAB1-1", "IAB12"],
  "livestream": false,
  "start_date": "2026-06-01",
  "end_date": "2026-06-02",
  "custom_fields": {},
  "created": "2026-01-14T15:30:00.000000Z",
  "updated": "2026-01-14T15:30:00.000000Z"
}

Note

If geo, iab_category, domain, or bundle are empty, the API responds with null for that field.

Data Partnership API Fields¶

Field	Type/Validators	Description
`id`	integer	Represents the internal Data Partnerships deal ID
`deal_id`	string	Represents the external deal ID
`fee_type`	string	Represents the type of curator fee. Supported types: `pct` and `cpm`
`fee_amount`	decimal	The amount paid as the curator fee. Can be decimal or integer. Should be `> 0` for `fee_type = cpm`; `0 < value <= 100` for `fee_type = pct`
`currency`	string	Represents the deal currency, supported values `USD` or `null`. Required for `fee_type = cpm`
`dsp`	integer	Represents Buyer ID in BidSwitch
`ssp`	string	Represents Supplier ID in BidSwitch
`geo`	array of strings	Represents the geolocation targeting by country(`US/CA`), region (`NY`), ,subregion, or `null` for an empty array.
`device_type`	array of strings	Represents supported device types. Supported values: `Phone`, `Tablet`, `PC`, `Media Center`
`content_type`	array of strings	Represents supported content types. Supported values: `display`, `native`, `video`, `audio`
`domain`	string	Represents domain targeting settings. Example `{ "type": "allow"\|"block", "values": [...] }`, `null` for an empty array
`bundle`	string	Represents app bundle targeting settings. Example `{ "type": "allow"\|"block", "values": [...] }`, `null` for an empty array
`inventory_type`	array of strings	Represents supported inventory types, for example `web`, `in_app`
`iab_category`	array of strings	Represents ontent category targeting settings. `null` should be used for an empty array
`livestream`	boolean	Represents the Livestream flag
`start_date` / `end_date`	string	Represent the deal flight dates. The start date cannot be earlier than the next day after the deal creation. The end date should be at least 1 day later than the start date. The end date cannot be equal or later than `2036-12-31`
`custom_fields`	object	Partner-specific extra fields
`created` and `updated`	string	Represent the deal timestamps

Custom Fields¶

Custom fields are partner-specific API fields added to deals under custom_fields object.

Partners’ custom fields are defined in code.
Matching uses the Data Partner’s internal name field.
Unknown custom fields in the deal payload raise a validation error.

Current behavior:

Integrations are registered in service code and matched exactly to DataPartner.name.
GET /api/v1/data_partners/ and GET /api/v1/data_partners/<id>/ expose the partner’s custom_fields_schema.
If a Data Partner has no registered integration, submitted custom_fields are ignored and stored as {}.
If a Data Partner has a registered integration, custom_fields must match that integration’s schema. The integration serializer validates required fields, field types, choices, and unknown fields.

Response Example With Custom Fields¶

{
  "id": 1,
  "name": "lumen",
  "name_external": "Lumen",
  "status": "active",
  "custom_fields_schema": [
    {
      "name": "min_lumen_attention_score",
      "verbose_name": "Attention Score",
      "type": "enum",
      "required": true,
      "choices": [
        {"value": "low", "display": "Low"},
        {"value": "medium", "display": "Medium"},
        {"value": "high", "display": "High"}
      ]
    }
  ]
}