Ad Tag Previews
SSL Compatibility
GDPR Compliancy
Ad Server Vendors
Internal Audits
Ad Validation Scanner
VAST Tag Validator
menu
Navbar

API v3.0 Introduction

Your API Endpoint

https://{your_name}.api.creativeqa.net/v3.0/

The API is organized around REST, and returns JSON for all responses. To use the API, sign up at the top right and your API key will be emailed within minutes.

Find your API endpoint URL here at the right.

Authentication

Add your API Key as a header

# Add the Authorization header to each request
curl "https://{your_name}.api.creativeqa.net/v3.0/"
  -H "X-ApiKey: {api_key}"
  -X POST

API Keys are used to authenticate requests. Add your key to each request as a header with the name X-ApiKey. Keep your API key private as much as you do with passwords. It's also used to sign in to your portal where you can find historical scans.

Rate Limits

Rate limits are calculated dynamically based on the load of the worker nodes. If no resources are available, the API will respond with a 400 HTTP code and an error message. It's generally recommended to wait for a response before sending a new one. To process batches of tags, submit them one by one instead of all at the same time.

Error Handling

Example of an error

{
    "error_type": "payload_error",
    "message": "There was an error."
}

Conventional HTTP response codes are used to indicate if a request failed or was successful. Codes in the 2xx range indicate success. Codes in the 4xx range indicate that the request failed. In that case, the JSON response will hold an error code and human-readable error message.

Error Types

authentication_error
string, solvable
The X-ApiKey header was not added or contained an invalid key. If revoked, generate a new API Key in your portal.
license_error
string, solvable
Your license has not been approved or has expired. Contact support for more information.
invalid_endpoint
string, solvable
An incorrect endpoint URL was used. Check for typos and make sure to use the endpoints from this documentation.
payload_error
string, solvable
The payload contained missing parameters or had an incorrect format. See the error message for details.
timeout
string, solvable
It took too long for the creative to load. Increase the default timeout manually if you wish to run the scan for a longer time.
processing_error
string, not solvable
The worker nodes weren't able to process your request. Please drop us a note to see if we could troubleshoot.

Change Log

Changes to the API are generally backwards compatible. If non-backwards compatible changes are introduced, the API version number in your endpoint URL will go up. Once you've reviewed the changelog and made the necessary changes at your side, you're invited to use the new API version by updating your endpoint URL accordingly.

QA Scans

Display Ads

curl "https://{your_name}.api.creativeqa.net/v3.0/scan/display"
  -H "X-ApiKey: {api_key}"
  -X POST
  -d ""

Example response

{
    "3pas": "",
    "blocked_by_adblock": false,
    "console": {
        "errors": [],
        "warnings": []
    },
    "cookies": [],
    "creative_rendered": true,
    "dialogs": [],
    "dimensions": {
        "height": 250,
        "width": 300
    },
    "has_video": false,
    "id": "",
    "iframes": {
        "count": 1
    },
    "landing_page": {
        "load_time": 0,
        "target": "",
        "url": ""
    },
    "local_storage": [],
    "meta": {
        "cpu": "AMD 16-Core EPYC 7302P",
        "device": "Desktop",
        "language": "en-US",
        "ram": "128GB",
        "scan_duration": "1.797165",
        "scan_type": "tag",
        "server_location": "wdc",
        "timestamp": 1607671300,
        "ua": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/87.0.4280.88 Safari\/537.36"
    },
    "metrics": {
        "cookies": {
            "percentile": 100,
            "value": 0
        },
        "cpu": {
            "percentile": 96,
            "value": 61
        },
        "domloaded": {
            "percentile": 100,
            "value": 159
        },
        "errors": {
            "percentile": 100,
            "value": 0
        },
        "iframes": {
            "percentile": 100,
            "value": 0
        },
        "load_size": {
            "percentile": 98,
            "value": 35892
        },
        "memory": {
            "percentile": 100,
            "value": 2662400
        },
        "painting": {
            "percentile": 54,
            "value": 9
        },
        "requests": {
            "percentile": 99,
            "value": 3
        },
        "scripting": {
            "percentile": 95,
            "value": 11
        }
    },
    "network": {
        "pixels": 0,
        "redirects": [],
        "responses": [{
            "url": "https:\/\/www.creativeqa.io\/inc\/example\/some_creative.js",
            "bytes": 296,
            "status": 200,
            "status_text": "",
            "is_pixel": false,
            "headers": {
                "date": "Fri, 11 Dec 2020 07:21:39 GMT",
                "content-encoding": "br",
                "last-modified": "Thu, 10 Dec 2020 21:16:45 GMT",
                "content-type": "application\/javascript"
            },
            "method": "GET",
            "resource_type": "script",
            "server_ip": "5.79.109.132",
            "ssl": true,
            "ssl_info": {
                "_subjectName": "localhost",
                "_issuer": "localhost",
                "_validFrom": 1607455037,
                "_validTo": 1922815037,
                "_protocol": "TLS 1.3",
                "_sanList": []
            }
        },
        {
            "url": "https:\/\/www.creativeqa.io\/inc\/example\/loader.js?referer=https:\/\/localhost\/tmp\/eb662-cd978-85147-71cb5.html",
            "bytes": 1476,
            "status": 200,
            "status_text": "",
            "is_pixel": false,
            "headers": {
                "date": "Fri, 11 Dec 2020 07:21:39 GMT",
                "content-encoding": "br",
                "last-modified": "Thu, 10 Dec 2020 21:16:45 GMT",
                "content-type": "application\/javascript"
            },
            "method": "GET",
            "resource_type": "script",
            "server_ip": "5.79.109.132",
            "ssl": true,
            "ssl_info": {
                "_subjectName": "localhost",
                "_issuer": "localhost",
                "_validFrom": 1607455037,
                "_validTo": 1922815037,
                "_protocol": "TLS 1.3",
                "_sanList": []
            }
        },
        {
            "url": "https:\/\/www.creativeqa.io\/inc\/example\/expedia.jpg",
            "bytes": 34120,
            "status": 200,
            "status_text": "",
            "is_pixel": false,
            "headers": {
                "date": "Fri, 11 Dec 2020 07:21:39 GMT",
                "last-modified": "Thu, 10 Dec 2020 21:16:45 GMT",
                "accept-ranges": "bytes",
                "content-length": "34120",
                "content-type": "image\/jpeg"
            },
            "method": "GET",
            "resource_type": "image",
            "server_ip": "5.79.109.132",
            "ssl": true,
            "ssl_info": {
                "_subjectName": "localhost",
                "_issuer": "localhost",
                "_validFrom": 1607455037,
                "_validTo": 1922815037,
                "_protocol": "TLS 1.3",
                "_sanList": []
            }
        }],
        "third_parties": 1,
        "total_bytes": 35892
    },
    "payload": {
        "allow_cache": true,
        "data": "PHNwYW4gaWQ9ZXhhbXBsZV91bml0Pjwvc3Bhbj4KPHNjcmlwdD4KICAgIHZhciBzID0gZG9jdW1lbnQuY3JlYXRlRWxlbWVudCgnc2NyaXB0Jyk7CiAgICBzLmFzeW5jID0gdHJ1ZTsKICAgIHMuc3JjID0gJ2h0dHBzOi8vd3d3LmNyZWF0aXZlcWEuaW8vaW5jL2V4YW1wbGUvc29tZV9jcmVhdGl2ZS5qcyc7CiAgICB2YXIgZWwgPSBkb2N1bWVudC5nZXRFbGVtZW50c0J5VGFnTmFtZSgnc2NyaXB0JylbMF07CiAgICBlbC5wYXJlbnROb2RlLmluc2VydEJlZm9yZShzLCBlbCk7Cjwvc2NyaXB0Pg==",
        "pdf": {
            "subtitle": "",
            "title": ""
        },
        "scan_type": "tag",
        "server_location": "wdc"
    },
    "responsive": true,
    "scan_id": "eb662-cd978-85147-71cb5",
    "screenshot": {
        "highres": {
            "background_color": "#76b2c1",
            "bytes": 36804,
            "mime_type": "image\/png",
            "url": "http:\/\/try.api.creativeqa.net\/cdn\/www.CreativeQA.io-123456-8b73w5hzkyam.png"
        }
    },
    "ssl_compliant": true,
    "tests": {
        "failed": [],
        "passed": [{
            "name": "Network Requests",
            "message": "A total of 3 HTTP requests were made (including pixels).",
            "expected": "<= 10 requests"
        },
        {
            "name": "Cookies Dropped",
            "message": "This ad doesn't seem to drop cookies.",
            "expected": "0 cookies"
        },
        {
            "name": "SSL-Compliancy",
            "message": "This tag is SSL-compliant.",
            "expected": "true"
        },
        {
            "name": "Adblock",
            "message": "This tag will likely not be blocked by ad blockers.",
            "expected": "false"
        },
        {
            "name": "Memory Usage",
            "message": "Memory usage is acceptable at 2.5 MB.",
            "expected": "< 5.0 MB"
        },
        {
            "name": "Mobile Responsive",
            "message": "The creative seems to be responsive on mobile devices.",
            "expected": "true"
        },
        {
            "name": "JavaScript Errors",
            "message": "No JavaScript errors have been detected.",
            "expected": "0 errors"
        },
        {
            "name": "Console Warnings",
            "message": "No console warnings have been detected.",
            "expected": "0 warnings"
        },
        {
            "name": "Dialogs and Modals",
            "message": "No interruptive dialogs have been detected.",
            "expected": "0 dialogs"
        },
        {
            "name": "Creative Visibility",
            "message": "The creative was loaded successfully.",
            "expected": "true"
        },
        {
            "name": "Ad Dimensions",
            "message": "This creative has dimensions 300x250px, which is a standard ad size.",
            "expected": "On acceptable list"
        },
        {
            "name": "Pixel Count",
            "message": "This creative fires 0 pixels, probably to measure impressions, viewability, etc.",
            "expected": "< 5 pixels"
        },
        {
            "name": "HTML5 localStorage",
            "message": "This ad doesn't seem to use HTML5 localStorage.",
            "expected": "0 localStorage objects"
        },
        {
            "name": "Video Stream",
            "message": "This ad doesn't seem to play videos.",
            "expected": "true or false"
        },
        {
            "name": "Click Tracking Macro",
            "message": "No click tracking macro has been detected, but that may be intentional.",
            "expected": "Any on list"
        }]
    },
    "pdf": {
        "url": "http:\/\/try.api.creativeqa.net\/cdn\/www.CreativeQA.io-123456-hkrf7gxnsyzm.pdf"
    },
    "json": {
        "url": "http:\/\/try.api.creativeqa.net\/cdn\/www.CreativeQA.io-123456-wak6sbp8ur2h.json"
    }
}

Two type of display ads can be scanned: standard ad tags and HTML5 Zip files. Add the ad tag or Zip file as a base64-encoded string to your API request. Note that the payload of the API request cannot exceed 5 MB.

Endpoint

POST https://{your_name}.api.creativeqa.net/v3.0/scan/display

Arguments

data
string, required
Either your ad tag or Zip file in base64-encoded format.
creative_type
string, required
Indicates what type of creative you've added. It should either equal ad_tag or zip.
server_location
string
The location of the server used to scan the creative:
  • sfo for San Francisco (USA)
  • wdc for Washington DC (USA)
  • ams for Amsterdam (The Netherlands)
  • fra for Frankfurt (Germany)
  • sgp for Singapore
Defaults to the server the closest to the source from which the API request was made.
timeout
int
Timeout in seconds after which the scan will be canceled. Range: 5 - 120. Defaults to 60 seconds.
pdf.title_base64
string
The title at the top in the PDF document. Defaults to the text "Creative QA Report".
pdf.subtitle_base64
string
The subtitle at the top in the PDF document.
pdf.text_base64
string
The text at the top in the PDF document.

Returns

3pas
string
The name of the third-party ad server, if detected successfully. Remains blank otherwise.
blocked_by_adblock
boolean
Wether or not the tag will likely be blocked by ad blockers.
console
array
Errors and warnings generated while loading the creative.
cookies
array
All cookies that were dropped by the creative. Make sure you comply with international privacy laws.
creative_rendered
boolean
Equals true in case something was painted on the screen, false otherwise.
dialogs
array
Any dialog message the creative shows as a pop-up. Generally created by alert() and confirm().
dimensions
array
The detected width and height of the creative.
has_video
boolean
Wether or not the creative plays video content.
iframes
array
An array with information about all iframes added to the page.
local_storage
array
All key/value pairs stored in window.localStorage.
meta
array
Meta-data about the scan, like the CPU used, the time it took to complete the scan, the server location, etc.
metrics
array
Some key performance metrics. Values are either in bytes, milliseconds or units. The percentiles are based on industry averages. For example, a 96 percentile for domloaded indicates that the ad is among the 4% fastest loading ads.
network
array
All HTTP requests and their responses. The key pixels indicates how many of those HTTP requests were 1x1 pixels.
responsive
boolean
Wether or not the ad is responsive on mobile devices.
scan_id
string
A unique ID assigned to the scan. Store this ID on your own backend to re-fetch result data at a later moment.
screenshot
array
A high-resolution screenshot of the creative. The url points to a PNG image. The background_color is in hex-format. It generally goes well with the main colors of the screenshot.
ssl_compliant
boolean
Wether or not the creative is SSL-compliant. If the creative tries to load assest over http, it will equal false.
tests
array
The most important part of the object. An array of all tests conducted and their results. The array is divided in failed/passed tests.
pdf
array
The url contains a link to the report PDF. The PDF can be loaded inside an iframe if you like.
json
array
The url contains a link to the JSON output of the scan.