Creative Approval Pre-submitting API

This API is used to pre-submit Creatives for Creative Approval (CA) with BidSwitch connected Suppliers. BidSwitch forwards each creative to the approval service of the specified Suppliers. The approval status of each submitted creative can then be checked using the Creative Approval Reporting API.

Process Overview

  1. Get your API Access Token. This requires creating an API user in the myBidSwitch UI, see the Getting API Credentials section for details.
  2. Using this Token, make a HTTP POST request to the BidSwitch CA endpoint. The POST request should contain your authentication details and the information about the Creatives being submitted for approval should be in JSON format, see the CA Submission Fields section for details.
  3. You can check which Creatives you have submitted using the Submitted Creatives Endpoint

Getting API Credentials

To get access credentials for the CA API, you need to create an API User Account in the myBidSwitch UI, using the following information.

Creating an API User

To create a user profile that can receive API Tokens, use the following steps:

  1. From the BidSwitch UI, select Users ‣ Add User.
  2. From the User Role dropdown menu, select API Account.

Getting an API Auth Token

To get your API token, make a HTTP POST request to the following URL. The response will contain your access token.

https://uauth.iponweb.com/oauth2/token/

The POST request must contain the following fields

grant_type=password
scope=service_id=api.bidswitch.com
username=<USERNAME> <!-- Your BidSwitch UI login -->
password=<PASSWORD> <!-- Your Bidswitch UI password -->

Authorization Response

{
  "token_type": "Bearer",
  "scope": "service_id=api.bidswitch.com",
  "access_token": "<your token>",
  "expires_in": 3600
}

Equivalent request via curl command:

$ curl https://uauth.iponweb.com/oauth2/token/ \
  --request POST \
  --data "grant_type=password" \
  --data "username=<username>" \
  --data "password=<password>" \
  --data "scope=service_id=api.bidswitch.com"

CA Submission Endpoints

Once you have your authorization token, you can make requests to the following endpoints.

<!-- Submitting Creatives Endpoint -->
https://api.bidswitch.com/creativeapproval/v1.0/pre-submit-creatives/register/

<!-- Viewing Submitted Creatives Endpoint -->
https://api.bidswitch.com/creativeapproval/v1.0/pre-submit-creatives/dsp/<dsp-id>/list/

Note

The endpoint for viewing submitted creatives does not return their approval status, see the Creative Approval Reporting API for that.

CA Submission Fields

The Creatives Object
Field Type Required Description
creatives Array of Objects Required This is the top level object that contains the details of each creative using the CA Description Fields.
CA Description Fields
Field Type Required Description
creative_id String Required The creative ID. The creative ID must take the following syntax: {DSP_ID}_{Creative_ID}, for example 70_650029457 or 79_0RsSUxZety0O1.
dsp_id Integer Required The ID of the Buyer from which the bid response originates.
ssps Array of strings Required A list of names specifying the Suppliers from whom approval is being sought.
creative_url String   The URL pointing to where the creative is hosted.
adm String   The HTML content of the creative.
preview_url String   A URL to preview the creative.
width Integer Required The width in pixels of the creative according to the log file.
height Integer Required The height in pixels of the creative according to the log file.
language String   The ISO 639-1 language code given in the Buyer bid response.
category String Required IAB category given in the Buyer bid response.
advertiser_name String Required Advertiser name.
type String Required The type of the creative, for examples: javascript, image, html, vast, adm.
agency_name String   Agency name.
landing_domains Array of strings   A List of landing domains.
country String   ISO 3166-1 alpha 2 code of the country where the creative is expected to be shown.
click_url String   The click URL for creatives without a direct link to a landing page.
seat_id String Required Seat ID from the Buyer bid response.
version Integer   The version of the creative. This must range between - 2³¹ to 2³¹ - 1. Usually a unix timestamp from the log file, or some other unique identifier.
yieldone_creative_ type String   A Yieldone specific field.
yieldone_creative_ category_id String   A Yieldone specific field.

Submission JSON Format

Each request should contain a list of creatives to be submitted for approval,mwith the required data to verify each.

{
    "creatives": [
        {
            "category": "IAB20-10",
            "dsp_id": 243,
            "advertiser_name": "TAM",
            "language": "en",
            "landing_domains": ["domain.example.com"],
            "creative_id": "243_BSW_TEST_1482424408",
            "preview_url": "https://example.com/dev-us/CreativeTest/TEST9871.mpg",
            "height": 600,
            "width": 160,
            "agency_name": "BSW Test Agency",
            "version": 1482424408,
            "country": "US",
            "creative_url": "https://example.com/dev-us/CreativeTest/TEST9871.mpg",
            "seat_id": "16",
            "type": "vast",
            "ssps": ["google"]
        },
        {
            "category": "IAB20-10",
            "dsp_id": 243,
            "advertiser_name": "TAM",
            "language": "en",
            "landing_domains": ["domain.example.com", "domain2.example.com"],
            "creative_id": "243_BSW_TEST_1482424409",
            "preview_url": "https://example.com/creative.png",
            "adm": "<html>...</html>",
            "height": 600,
            "width": 160,
            "agency_name": "BSW Test Agency",
            "version": 1482424409,
            "country": "US",
            "seat_id": "16",
            "type": "vast",
            "ssps": ["google"]
        }
    ]
}

Uploading Script

You can use the example CA Upload Script, or the below CLI example to submit creatives for approval. In the following example POST request:

  • ${TOKEN} is your API Auth Token.
  • CREATIVE is the list of creatives being submitted, this can also be a file such as creative-approval.json. See the CA Submission Fields and Submission JSON Format sections to properly format the JSON data.
CREATIVE='{ "creatives": [] }'

curl --request POST --data "$CREATIVE"\
           -H "Accept:application/json" -H "Authorization:Bearer ${TOKEN}" \
           -H 'Content-Type:application/json' \
           --insecure \
           https://api.bidswitch.com/creativeapproval/v1.0/pre-submit-creatives/register/

Uploading Responses

The server returns either a 200 or 400 HTTP response. Each response will have a JSON formatted status describing what happened with the submitted data. The following statuses can be returned:

  • Success: All Creatives have been properly submitted for approval.
  • Partial Success: The submission was correct and any valid creatives have been submitted for approval, but some of the creatives were invalid and could not be registered. In this case the errors field will describe what exactly has gone wrong.
  • Error: Errors can occur for various reasons, see the error message for specific details, and use the following steps to remedy these common causes:
    • No Permissions: Check that your Buyer ID or Auth Token are valid, and specified correctly.
    • non_field_errors: Some required fields are missing from the JSON file, check that the JSON format is correct.
    • Invalid creatives: In this case the response will come with HTTP status code 400 and the errors field will contain an array of nulls and objects describing the errors, where every null or error has the same index as the creative connected to that success or error. For example: [null, null, {"version": ["invalid version"]}]. In this example the first two submitted creatives were accepted, while the third failed.
# Example  of a good response (status code 200):
{"status":"success"}

# Example of a response with error list (status code 200):
{"status":"error","errors":[{"dsp_id":["You have no permissions to submit creatives using DSP ID 243"]}]}

# Example of a response with invalid data (status code 400):
{"status":"error","errors":{"non_field_errors":["\'creatives\' is a required property"]}}

Viewing Submitted Creatives

To view details about Creatives submitted for CA approval, you need to make a GET request to the appropriate endpoint, using a valid authorization token and specifying your $DSP_ID in the URL.

curl -H "Accept:application/json" -H "Authorization:Bearer ${TOKEN}" \
        -H 'Content-Type:application/json' \
        --insecure \
        https://api.bidswitch.com/creativeapproval/v1.0/pre-submit-creatives/dsp/${DSP_ID}/list/

You can also use the Viewing Submitted Creatives Script. This works with both Python 2.7 and 3+, though it requires the requests library. For requests information, see http://docs.python-requests.org/en/master/

Viewing CA Response

{
    "creatives": [
        {
            "category": "IAB20-10",
            "dsp_id": 243,
            "advertiser_name": "TAM",
            "language": "en",
            "landing_domains": ["domain.example.com"],
            "creative_id": "243_BSW_TEST_1482424408",
            "preview_url": "https://example.com/dev-us/CreativeTest/TEST9871.mpg",
            "height": 600,
            "width": 160,
            "agency_name": "BSW Test Agency",
            "version": 1482424408,
            "country": "US",
            "creative_url": "https://example.com/dev-us/CreativeTest/TEST9871.mpg",
            "seat_id": "16",
            "type": "vast",
            "ssps": ["google"]
        }
    ]
}

Viewing Error Response

# Example of a response in case of no permission to view specified dsp
# Creatives (status code 403):
{"status":"error","errors":["You have no permission for that."]}

Use Cases

A number of Suppliers have Creative Approval (CA) processes that are slightly different to the usual processes, and require using the Pre-Submit CA API. You can read more about each in the Supplier Information section.

The Pre-Submit CA Submitting API can be used to submit Creatives for approval to each of their CA services. To do this, specify the one you need in the ssps field, assuming you also have the other required fields filled out, and have set up a trading relationship. You can also check the list of supported Suppliers in the Suppliers Integrated with the BidSwitch CA Services section.

  • Broadsign "broadsign"
  • Dish TV "dish"
  • Sorenson Media "sorenson"
{
    "creatives": [
        {
            "ssps": ["dish", "broadsign", "sorenson"]
        }
    ]
}

Viewing Creative Status Changes

To get a log of all changes to a creative’s status as it passed though the approval process, make a GET request with an auth token specifying the creative_id in the URL.

Request

# ${TOKEN} is your API Auth Token
# ${CREATIVE_ID} is the ID of the creative you want to get the history of

curl -H "Accept:application/json" \
     -H "Authorization:Bearer ${TOKEN}" \
     -H 'Content-Type:application/json' \
     --insecure \
     https://api.bidswitch.com/creativeapproval/v1.0/creatives/log/${CREATIVE_ID}

Response

{
    "status": "success",
    "log": [
        {
            "created": "2017-10-10 10:12:11",
            "provider": "ssp-name",
            "message": "Creative submitted"
        },
        {
            "created": "2017-10-11 12:14:01",
            "provider": "ssp-name",
            "message": "Status was changed: submitted -> approved"
        }
    ]
}