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 API Authorization 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

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

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

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.

{
    "creatives": [
        {
            "ssps": ["broadsign"]
        }
    ]
}

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"
        }
    ]
}