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¶

Get your API Access Token. This requires creating an API user in the myBidSwitch UI, see the API Authorization section for details.
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.
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"
        }
    ]
}