Campaign Objects Service

The Prebid Server Premium (PSP) UI allows configuration creation, including targeting (geographic location, device, key value, etc.) and demand partner mapping, in a single workflow. See Create a New PSP Configuration for context and UI guidance.

Creating such configurations via API requires the PSP campaign objects service, detailed below, to set the desired targeting. The response from this service includes a lineItem.id which is then set as the targeting_id in the configuration service.

The new PSP campaign objects service:

• Creates an advertiser (if a PSP advertiser does not exist).
• Creates an insertion order (if a PSP insertion order does not exist).
• For each call, creates a new profile and line item pair.

These are PSP-specific shell objects that do not deliver but are necessary for the targeting profile to be evaluated by the Monetize Platform. Only the profile portion is relevant to the publisher for any POST/PUT calls to this PSP service.

It is recommended to manage these configurations and their targeting in the PSP UI, but for large publishers or those with automation, API interaction is required or at least preferred.

High-level workflow

1. Make a POST request to https://api.appnexus.com/prebid/psp-campaign-objects with the desired targeting.
2. Record the lineItem.id value.
3. Make a POST/PUT request to https://api.appnexus.com/prebid/config where the targeting_id is the lineItem.id from the PSP campaign objects service response.

REST API

POST

POST: Parameters

POST Response

Creating objects

1. Make a POST request to https://api.appnexus.com/prebid/psp-campaign-objects.

   1. Include a top-level profile object.

   2. The profile object must include a name string an ad_type_targets array of objects.

   3. The profile object must contain any desired targeting as documented in the profile service.

      Note

      In the profile service documenatation certain fields, such as country_targets, include a corresponding _action field, like country_action. The _action field can be set to either include or exclude. If set to include, the corresponding object or array (e.g., country_targets) must be populated for the targeting to work properly.

   4. Values to populate within the profile can be found in read-only services, such as the country service. These are linked in the profile service documentation.

Example profile request

   
{
    "profile": {
        "name": "Test Profile",
        "ad_type_targets": [
            {
                "id": 1
            },
            {
                "id": 2
            }
        ],
        "country_action": "include",
        "country_targets": [
            {
                "id": 233,
                "name": "United States",
                "code": "US",
                "active": true
            },
            {
                "id": 41,
                "name": "Canada",
                "code": "CA",
                "active": true
            },
            {
                "id": 80,
                "name": "United Kingdom",
                "code": "UK",
                "active": true
            }
        ]
    }
}

2. The PSP campaign objects service will respond with the details of the objects created:

   1. advertiser: Created if one did not already exist for PSP.
   2. insertionOrder: Created if one did not already exist for PSP.
   3. profile: Contains all of the targeting.
   4. lineItem: Includes the id value, which will be used as the targeting_id in the PSP Configuration Service.

3. Make a POST or PUT request to https://api.appnexus.com/prebid/config documentation.

   1. targeting_id is the lineItem.id from the PSP campaign objects service response.
   2. targeting_metadata.priority is an integer 1 through 20.
      1. Each auction uses one configuration.
      2. If the targeting of multiple configurations overlaps, the targeting_metadata.priority determines which configuration is chosen, with 20 being the highest priority.

Example configuration request

Append the configuration ID as the last component of the URL.

{
    "name": "Test Configuration",
    "targeting_id": 26831593,
    "enabled": true,
    "targeting_metadata": {
        "priority": 18
    },
    "demand_partner_config_params": [
        {
            "name": "appnexus",
            "params": {
                "placement_id": 123456
            }
        }
    ]
}
    

4. The configuration service will respond confirming the details of the objects (configuration, and optionally demand partner configuration parameters) created.

PUT

Editing objects

1. Retrieve the details of the profile created earlier by the PSP campaign objects service. Refer to the profile service documentation:

   1. If the advertiser.id from the previous call to the PSP campaign objects service is not known is not known, refer to the advertiser service documentation. Make a GET request to https://api.appnexus.com/advertiser.
   2. Make a GET request to https://api.appnexus.com/profile?advertiser_id=ADVERTISERID to retrieve all profiles for the advertiser, or https://api.appnexus.com/profile?code=PROFILEID&advertiser_code=ADVERTISERID to retrieve a specific profile.
   3. The Profile service will respond with the full profile object, containing all possible targeting fields. Although PATCH requests to PSP campaign objects are not supported, the PUT request only needs to include the profile targeting elements to be updated.
   4. If the lineItem.id is not known, refer to the line item service documentation. Make a GET request to https://api.appnexus.com/line-item.

2. Make a PUT request to https://api.appnexus.com/prebid/psp-campaign-objects?profileId=PROFILEID&lineItemId=LINEITEMID

   1. Include a top-level profile object.
   2. The profile object must contain any desired targeting changes as documented in the profile service.

Example call using curl

    
{
    "profile": {
        "ad_type_targets": [
            {
                "id": 1
            }
        ],
        "country_action": "include",
        "country_targets": [
            {
                "id": 233,
                "name": "United States",
                "code": "US",
                "active": true
            },
            {
                "id": 41,
                "name": "Canada",
                "code": "CA",
                "active": true
            },
            {
                "id": 80,
                "name": "United Kingdom",
                "code": "UK",
                "active": true
            },
            {
                "id": 34,
                "name": "Brazil",
                "code": "BR",
                "active": true
            }
        ]
    }
}

3. The PSP campaign objects service will respond with the details of the objects updated.

DELETE

To delete a line item created by the campaign objects endpoint, include the lineItemId in the query string.

DELETE: Example call using curl

curl -X DELETE https://api.appnexus.com/prebid/psp-campaign-objects?lineItemId=12345

DELETE: Response

On success, the line item indicated will be returned as a JSON object with the deleted property set to true. It will no longer be available within the system. All sub-objects will also be deleted.

Related topics

• Configuration Service
• Cross-Partner Settings Service
• Demand Partner Service
• Demand Partner Schema Service
• Prebid Demand Partner Params Service
• Create a New PSP Configuration
• Prebid Server Premium Demand Partner Integrations
• Common Issues and Best Practices