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. Once created you can get get a permanent token or request short lived temporary tokens:

  1. From the BidSwitch UI, select Users ‣ Add User.

  2. From the User Role dropdown menu, select API Account.

Permanent Auth Tokens

To get a permanent auth token for your integration, use the following steps.

  1. Log into the BidSwitch single sign-on management portal: https://uauth.bidswitch.com/uauth/settings/#sso

  2. Select OAuth2 Access Token ‣ New Permanent Token

  3. Set the scope to api.bidswitch.com, and Create

  4. Save the generated token for use with your API requests, this token must be passed in request headers

Temporary Auth Tokens

To get a temporary auth token for your integration, use the following steps. Make an HTTP POST request to the following URL. The response will contain your access token and its expiration time. You can use this token to perform API requests until the token expires.

Auth Token POST Details

Endpoint Info

Description

endpoint

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

Method

POST

headers

Content-Type and Accept {'Content-Type': 'application/x-www-form-urlencoded', 'accept': 'application/json'}

username

(Required) Your UI username

password

(Required) Your UI password

scope

(Required) The service to which your user token should grant you access, e.g. "scope=service_id=api.bidswitch.com"

Example Using Curl
curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'accept: application/json' -d 'grant_type=password&username=${username}&password=${password}&scope=service_id=api.bidswitch.com' 'https://uauth.iponweb.com/oauth2/token/'
Example Using Python Requests
#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import json
import requests

headers = {
    "Content-Type": "application/x-www-form-urlencoded",
    "accept": "application/json",
}
payload = {
    "grant_type": "password",
    "username": login,  # Your UI Login
    "password": password,  # Your UI Password
    "scope": "service_id=api.bidswitch.com",
}
token_post = requests.post(
    "https://uauth.iponweb.com/oauth2/token/", params=payload, headers=headers
)
response_json = token_post.json()
token = response_json["access_token"]

print(token)
Sample AUTH Response
{
  "token_type": "Bearer",
  "scope": "api.bidswitch.com",
  "access_token": "<access_token>",
  "expires_in": 3600,
  "last_chars": "<last chars of auth token>"
}

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 https://requests.readthedocs.io/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"
        }
    ]
}