Deal Line Item API setup guide

Setting up an API implementation of a Deal Line Item to target a deal requires configuring a number of different properties on different API objects. This guide will explain the process of creating and configuring a deal line item using our API.

Overview

Deal line items are a powerful feature that allows network and publisher clients to better support their buyers by providing prepackaged, user-friendly buying tools.

Setting up a deal line item typically involves making requests to the following API service endpoints to access or create the corresponding API objects:

This guide uses cURL examples for all requests. You can use other API request tools (e.g., Postman), but you’ll then need to adjust the examples accordingly.

Prerequisites

Before beginning this setup, be sure to read API Getting Started. It provides information on testing environments, usage constraints, API semantics (running commands, filtering, sorting, etc.), and best practices.

Order of operations

API objects often have dependencies on other API objects and there is an order you must follow in creating or accessing objects when you create a deal line item. For example, you must provide the IDs of the following API objects: 
- advertiser
- insertion-order
- deal
- profile.

To obtain the IDs for these objects, you'll need to either create them or already have access to them. The steps in this guide follow the typical order of operations required to create a deal line item.

Best practices

For a general list of best practices to follow when working with the API, see API Best Practices. The following are some best practices that are specific to a deal line item setup:

• Set the state field of the deal line item to "inactive" until the line item is fully configured and ready for testing.
• Note the ID of any objects you create. The IDs of objects you create are returned in the response body of requests. You'll often need these IDs later so copying them when they're returned can reduce the number of additional GET requests you have to make to obtain them.

Setup procedure

The following steps will guide you through the process of setting up a deal line item with typical configurations:

• Step 1 - Obtain an authorization token
• Step 2 - Create or access an advertiser
• Step 3 - Create or access an insertion order
• Step 4 - Create a deal
• Step 5 - Create a deal line item profile
• Step 6 - Create a deal line item

Authentication

Step 1 - Obtain an authorization token

First, you’ll need to obtain an authorization token. You must then include this authorization token in all subsequent requests (see Authentication Service for more information). To obtain an authorization token, do the following:

1. Create a JSON file containing your username and password.

   {
       "auth": {
           "username" : "USERNAME",
           "password" : "PASSWORD"
       }
   }
   

2. Make a POST request to the /auth endpoint with this JSON file in the request body (see Authentication Service for more information). In the cURL request below, the authorization token returned is stored in the “cookies” file.

   curl -c cookies -X POST -d @authentication.json 'https://api.appnexus.com/auth'
   

3. Check the response body of your request (see Example Response below). If your request was successful, you’ll get a "status" of “OK” and the "token" field will be populated with the authentication token value.
   
   Example response

   {
      "response" : {
         "token" : "authn:225692:2d787d1838283:lax1",
         "status" : "OK"      
      }
   }
   

Advertiser

Step 2 - Create or access an advertiser

You'll need to create or access an advertiser from which to create a deal line item. For deal line items, advertisers are set up the same way as augmented line items.

JSON fields for advertiser (required and useful optional fields)

If you don't already have an advertiser to use, create an advertiser by doing the following (see Advertiser Service for more information):

1. Create an advertiser JSON:

   $ cat advertiser.json
   {
       "advertiser": {
           "name": "Deal Line Item Example Advertiser",
           "timezone": "US/Pacific"
       }
   }
   

2. Make a POST request to the https://api.appnexus.com/advertiser endpoint with this advertiser JSON and an appropriate member_id.

   $ curl -b cookies -c cookies -X POST -d @advertiser.json 'https://api.appnexus.com/advertiser?member_id=2378'
   

3. Check the response body of your request. If your request was successful, you’ll get a "status" of “OK” and you’ll see the updates you made.

4. Note the advertiser ID in the response body so you can use it when you create the deal line item in Step 6 - Create a deal line item

Insertion order

Step 3 - Create or access an insertion order

You'll need to create or access an insertion order to create a deal line item. Deal line items require a seamless insertion order (see required fields below).

JSON fields for seamless insertion order (required and useful optional fields)

If you don't already have an insertion order to use, create an insertion order by doing the following (see Insertion Order Service for more information):

1. Create an insertion order JSON (two examples are shown below):

   Example JSON: No end date, no budget

   $ cat insertion-order-noenddate.json
   {
       "insertion-order": {
           "name": "Deal Line Item Example IO",
           "budget_intervals": [{
               "start_date": "2019-10-10 00:00:00",
               "end_date": null,
               "daily_budget": null,
               "daily_budget_imps": null,
               "enable_pacing": true,
               "lifetime_budget": null,
               "lifetime_budget_imps": null,
               "lifetime_pacing": false
           }],
           "budget_type": "impression"
       }
   }
   

   Example JSON: flights, impression budgets

   $ cat insertion-order-flights.json
   {
       "insertion-order": {
           "name": "Deal Line Item Example IO",
           "budget_intervals": [
   
               {
                   "start_date": "2019-10-10 00:00:00",
                   "end_date": "2019-10-12 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 980,
                   "lifetime_pacing": false
               },
               {
                   "start_date": "2019-10-13 00:00:00",
                   "end_date": "2019-10-18 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 100,
                   "lifetime_pacing": false
               }
           "budget_type": "impression"
           ]
       }
   }
   

2. Make a POST request to the https://api.appnexus.com/insertion-order endpoint with this insertion order JSON and an appropriate advertiser_id and member_id.

   Example request: no end date, no budget

   $ curl -b cookies -c cookies -X POST -d @insertion-order-noenddate.json 'https://api.appnexus.com/insertion-order?advertiser_id=2605036&member_id=2378'
   

   Example request: flights, impression budgets

   $ curl -b cookies -c cookies -X POST -d @insertion-order-flights.json 'https://api.appnexus.com/insertion-order?advertiser_id=2605036&member_id=2378'
   

3. Check the response body of your request. If your request was successful, you’ll get a "status" of “OK” and you’ll see the updates you made.

4. Note the insertion order ID in the response body so you can use it when you create the deal line item in Step 6 - Create a deal line item.

Deal

Step 4 - Create a deal

You'll need to create the deal you want to associate with the deal line item.

JSON fields for deal

Useful optional JSON fields

JSON fields for allowed creatives

Brand (see Brand Service)

Brand example

"brand_restrict": true,
            "brands": [
                {
                    "id": 2,
                    "name": "1800Flowers",
                    "override": true
                },
                {
                    "id": 4,
                    "name": "Acura",
                    "override": false
                }
            ] 

Language (see Language Service)

Language example

"language_restrict": true,
            "languages": [
                {
                    "id": 1,
                    "name": "English",
                    "override": false
                },
                {
                    "id": 2,
                    "name": "Chinese",
                    "override": true
                }
            ]

Trust level

Trust level example

"audit_status_option": "max_trust" 

Creative category

Creative category example

"categories": [
                 {
                     "id": 1,
                     "name": "Airlines",
                     "override": false
                 },
                 {
                     "id": 2,
                     "name": "Apparel",
                     "override": true
                 }
             ],
             "category_restrict": true

Specific creatives

Specific creatives example

"creatives": [
                {
                    "id": 161501729,
                    "status": "banned"
                },
                {
                    "id": 161501882,
                    "status": "approved"
                }
            ]

Media type (see Media Subtype Service and Media Type Service)

Media type example

"allowed_media_subtypes": [
                 {
                     "id": 2,
                     "last_modified": "2015-09-17 19:19:21",
                     "media_type": {
                         "id": 2,
                         "media_type_group_id": 2,
                         "name": "Pop",
                         "uses_sizes": "sometimes"
                     },
                     "name": "Popup",
                     "native_assets": null,
                     "permitted_sizes": null
                 }
             ],
 "allowed_media_types": [
                 {
                     "id": 1,
                     "last_modified": "2012-03-16 21:36:10",
                     "media_type_group_id": 1,
                     "name": "Banner",
                     "uses_sizes": "always"
                 },
                 {
                     "id": 4,
                     "last_modified": "2016-08-22 16:23:12",
                     "media_type_group_id": 1,
                     "name": "Video",
                     "uses_sizes": "never"
                 }
             ]

Technical Attributes (see Technical Attribute Service)

Technical attributes example

"technical_attribute_restrict": false,
             "technical_attributes": [
                 {
                     "id": 1,
                     "name": "Image",
                     "override": true
                 }
             ]

JSON fields for deal data protection (see Visibility Profile Service)

User ID and device ID

Protect user ID and device ID example

Step 1: Create a visibility profile

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_device_id_default": false,
        "expose_user_id_default": false,
        "name": "Deal Visibility Profile"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

Step 2: Associate the visibility profile to the deal and enable data protection

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

IP address

Protect IP address example

Step 1: Create a visibility profile

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_ip_default": false,
        "ip_exposure_default": "truncated",
        "name": "Deal Visibility Profile - Hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

Step 2: Associate the visibility profile to the deal and enable data protection

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

URL

Protect domain example

Step 1: Create a visibility profile

> cat visibility_profile.json
{
    "visibility-profile": {
        "name": "Deal Visibility Profile - Hidden",
        "url_exposure_default": "hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

Step 2: Associate the visibility profile to the deal and enable data protection

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

Add to Segment (see Deal Service)

Prevent adding to segment on click or view example

> cat add_segment.json
{
    "deal": {
        "allow_creative_add_on_click": false,
        "allow_creative_add_on_view": false
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @add_segment.json 'https://api.appnexus.com/deal?id=123456'

To create a deal, do the following (see Deal Service for more information):

1. Create a deal JSON:

   $ cat deal.json
   {
       "deal": {
           "name": "Deal Line Item Example Deal",
           "buyer": {
               "id": 2379
           },
           "version": 2
       }
   }
   

2. Make a POST request to the https://api.appnexus.com/deal endpoint with this deal JSON and an appropriate member_id.

   $ curl -b cookies -c cookies -X POST -d @deal.json 'https://api.appnexus.com/deal?member_id=2378'
   

3. Check the response body of your request. If your request was successful, you’ll get a "status" of “OK” and you’ll see the updates you made.

4. Note the deal ID in the response body so you can use it when you create the deal line item in Step 6 - Create a deal line item.

Profile

Step 5 - Create a deal line item profile

Next, create a deal line item profile to use in targeting with the deal line item. Be sure to note the ID for this profile for later use. See Profile Service for more information.

Optional JSON fields for deal line item profile

There are many optional fields available in the deal line item profile for targeting with the deal line item. For example, you can target properties associated with inventory, inventory types, allowlists, blocklists, device types, and so forth. See the Profile Service for more information on available fields.

To create a deal line item profile, do the following (see Profile Service for more information):

1. Create a deal line item profile JSON:

   Example: Profile creation with country, frequency/recency caps, and view rate/completion rate thresholds

   $ cat profile.json
   
   {
       "profile": {
           "country_action": "include",
           "country_targets": [{
               "active": true,
               "code": "US",
               "id": 233,
               "name": "United States"
           }],
           "engagement_rate_targets": [{
                   "engagement_rate_pct": 25,
                   "engagement_rate_type": "video_completion"
               },
               {
                   "engagement_rate_pct": 50,
                   "engagement_rate_type": "predicted_iab_video_view_rate"
               }
           ],
           "max_day_imps": 10,
           "min_minutes_per_imp": 300
       }
   }
   

   Example: Profile creation without targeting

   > cat profile.json
   
   {
       "profile": {
       }
   }
   

2. Make a POST request to the https://api.appnexus.com/profile endpoint with this deal profile JSON and an appropriate advertiser_id.

   Example: Profile creation with country, frequency recency caps, and view rate/completion rate thresholds

   > curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
   

   Example: Profile creation without targeting

   > curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
   

3. Check the response body of your request. If your request was successful, you’ll get a "status" of “OK” and you’ll see the updates you made.

4. Note the profile ID in the response body so you can use it when you create the deal line item in Step 6 - Create a deal line item.

Line Item

Step 6 - Create a deal line item

Finally, you'll need to create the deal line item to associate the deal ID and the deal line item profile you created in Step 5 - Create a deal line item profile.

JSON fields for deal line item

Useful optional JSON fields

To create a deal line item, do the following (see Line Item Service for more information):

1. Create a deal line item JSON (you'll need an existing advertiser ID, insertion order ID, deal ID, and profile ID).

   Example JSON: Deal line item no budget

   > cat deal_line_item.json
   {
       "line-item": {
           "ad_types": ["video"],
           "auction_event": {
               "kpi_auction_type_id": 1,
               "payment_auction_type_id": 1,
               "revenue_auction_type_id": 1
           },
           "bid_object_type": "deal",
           "budget_intervals": [{
               "start_date": "2019-10-11 12:00:00"
           }],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

   Example JSON: Deal line item lifetime impression budget

   > cat deal_line_item_lifetime.json
   {
       "line-item": {
           "ad_types": ["video"],
           "auction_event": {
               "kpi_auction_type_id": 1,
               "payment_auction_type_id": 1,
               "revenue_auction_type_id": 1
           },
           "bid_object_type": "deal",
           "budget_intervals": [
                   {
                       "end_date": "2019-10-18 23:59:59",
                       "lifetime_budget_imps": 2586,
                       "start_date": "2019-10-11 12:00:00",
                       "timezone": "US/Pacific"
                   },
                   {
                       "end_date": "2019-10-25 23:59:59",
                       "lifetime_budget_imps": 2414,
                       "start_date": "2019-10-19 00:00:00",
                       "timezone": "US/Pacific"
                   }
               ],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

   Example JSON: Deal line item daily revenue budget

   > cat deal_line_item_daily.json
   {
       "line-item": {
           "ad_types": ["video"],
           "auction_event": {
               "kpi_auction_type_id": 1,
               "payment_auction_type_id": 1,
               "revenue_auction_type_id": 1
           },
           "bid_object_type": "deal",
           "budget_intervals": [
                   {
                       "daily_budget_imps": 270,
                       "end_date": "2019-10-18 23:59:59",
                       "start_date": "2019-10-11 12:00:00",
                       "timezone": "US/Pacific"
                   }
               ],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

2. Make a POST request to the https://api.appnexus.com/line-item endpoint using this deal line item JSON and an appropriate advertiser_id and member_id.

    Example request: Deal line item no budget

   > curl -b cookies -c cookies -X POST -d @deal_line_item.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

    Example request: Deal line item lifetime impression budget

   > curl -b cookies -c cookies -X POST -d @deal_line_item_lifetime.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

    Example request: Deal line item daily revenue budget

   > curl -b cookies -c cookies -X POST -d @deal_line_item_daily.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

3. Check the response body of your request. If your request was successful, you’ll get a "status" of “OK” and you’ll see the updates you made.

4. Note the line item ID in the response body so you can identify this deal line item later to change its state (active or inactive) or modify it.

Related topics

• API Getting Started
• API Best Practices
• API Semantics
• Deal Service
• Line Item Service (ALI)
• Profile Service