Curator Migration: Updated API Guidance (May 2024)

One of the main enhancements provided by the migration to Commerce Grid is the evolution from a three-layered deal packaging structure (Supply Deal -> Package -> Demand Deal) to a two-layered structure (Supply Package -> Demand Deal).

This change simplifies the operational flow and minimizes the number of steps needed to execute deal creation for Commerce Grid curation API users.

Here's a snapshot of what API curators need to know:

1. There are no changes to the API endpoint (curate.themediagrid.com/api) currently in use, rather it's the structure of entities that is changing. Continue using this endpoint for all your existing and new supply packaging needs.

2. The "Package" entity is not needed anymore and shouldn't be used following migration, as outlined in this document. We will deprecate this entity by June 30th, 2024; thus, we encourage API users to migrate scripts over to the new two-layer structure prior to this date.

3. Supply packages and demand deals can now be created with a single request

The 'Package' entity will be deprecated and removed by June 30th, 2024.

As we move from the three-layered scheme to the two-layered scheme, curators will gain the ability to simply associate 'Supply Deals' directly with 'Demand Deals' without 'Package' needed in between as an intermediary entity. This removes the need to create packages specifying 'Supply Deals' and 'Seats'.

As part of the improvements generated by the new two-layer scheme, curators can create a Supply Package and a linked Demand Deal by sending a single POST request.

To create Supply Packages and Demand deals together you will need to specify only one additional field when creating a supply package: create_demand_deals or demand_deals.

Using the field create_demand_deals you can create Demand Deals and set options for each seat. You will no longer need to create a Package separately and edit automatically created Demand Deals.

"create_demand_deals": { "demand_deals_options": [ { "seat": { "id": 0, "name": "string" }, "price": 0.01, "deal_sync": true } ], "agency_curation_fee": 0, "agency_curation_fee_type": 0, "contact_email": "string" }

You can also use the field demand_deals to link some of your Demand Deals that you have previously created to a supply package. You can populate this field with Demand Deals information obtained in the response from other requests.

"demand_deals": [ { "id": 0, "name": "string" } ]

The following examples detail how to put these new fields into use.

Example 1: Creating a new Supply Package and new Deals (Generate new Demand deal for each selected Seat)

In the code blocks below, we demonstrate how the new field create_demand_deals can be used to create several demand deals with different seats and pricing rules.

POST https://curate.themediagrid.com/api/supply_deals/.

Request body:

{ 'app_list_targetings': [], 'browser_targetings': [], 'device_targetings': [], 'domain_list_targetings': [], 'end_date': None, 'geo_targetings': [], 'is_active': True, 'is_dynamic_bidding': True, 'is_true_price_opt_enable': False, 'media_type': 'banner', 'name': 'Test 123', 'operating_system_targetings': [], 'size_targetings': [], 'start_date': '2024-04-04 00:00:00+0000', 'create_demand_deals': { 'agency_curation_fee': 1, 'agency_curation_fee_type': 0, 'demand_deals_options': [{ {'id': < Your seat ID >}, }], 'contact_email': 'contact_email@example.com' } }

Response:

{ 'demand_deals': [{ // list of generated demand deals 'id': 456789, 'name': 'Test SP 123: Test Seat 123' }], 'id': 123456, 'name': 'Test 123', 'packages': [{ // deprecated field, will disappear after June 30 'id': 567890, 'name': 'Package for: Test SP 123: Test Seat 123' }], ... (other fields) }

Example 2: Create a new Supply Package and Add to an existing Demand Deal(s)

The new field demand_deals can be used to link a new Supply Package to existing Demand Deals

POST https://curate.themediagrid.com/api/supply_deals/

Request body:

{ 'app_list_targetings': [], 'browser_targetings': [], 'device_targetings': [], 'domain_list_targetings': [], 'end_date': None, 'geo_targetings': [], 'is_active': True, 'is_dynamic_bidding': True, 'is_true_price_opt_enable': False, 'media_type': 'banner', 'name': 'Test 123', 'operating_system_targetings': [], 'size_targetings': [], 'start_date': '2024-04-04 00:00:00+0000', 'demand_deals': [{ 'id': 234567, }],

Response:

{ 'demand_deals': [{'id': 234567, 'name': 'Test Package 123: Test Seat 123'}] 'id': 123456, 'name': 'Test 123', 'packages': [{ // deprecated field, will disappear after June 30th 'id': 345678, 'name': 'Test Package 123' }], ... (other fields) }

Example 3: Editing an existing Demand Deal

Use Demand Deal ID in GET or PUT methods from the previous step (see 'demand_deals' field in response) to access your demand deal, view it and / or make changes.

GET https://curate.themediagrid.com/api/demand_deals/234567/

Response:

{ 'id': 234567, 'name': 'Test Package 123 : Test Seat 123', 'package': { deprecated field 'id': 345678, 'name': 'Test Package 123' }, 'seat': <Your seat ID object>, 'dsp': <DSP object of the the selected seat>, 'supply_deals': [{ 'id': 123456, 'name': 'Test Deal 123', ... (other supply deal fields) }], ... (other fields) }