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:
|
| 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.
|