Create a Screenshot Request
Creates a screenshot request from provided data
Organization slug
abc-company
Authorization
Please take a screenshot of the ad on the homepage of the site
POST /api/v1/orgs/{organization_slug}/screenshot_requests HTTP/1.1
Host: app.adreform.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 622
{
"campaign": {
"id": "8304d4b0-90e0-4c58-ae3d-38807b23fd9c",
"name": "New Campaign - Via API"
},
"screenshot_requests": [
{
"ad": {
"id": "9d3df05e-7e9d-41c2-80d2-28ccc36960e9",
"lookup_key": "my-internal-key-0001",
"media": {
"type": "html_tag",
"content": "<img src=\"https://picsum.photos/300/250?image=0\"/>"
}
},
"screenshots": [
{
"site": {
"url": "https://atlutd.com"
},
"device": {
"name": "desktop"
}
}
]
}
],
"subscribers": [
{
"webhook": {
"url": "https://webhook.site/ae28ba3d-7c83-4a52-a0e4-5925f76d3a14"
},
"s3": {
"bucket": "my-bucket",
"region": "us-east-1",
"key_prefix": "ar_"
}
}
],
"instructions": "Please take a screenshot of the ad on the homepage of the site"
}
{
"type": "screenshot_set",
"id": "e9b4c72e-7520-4e3f-a3e8-a092b927f0d4",
"status": "draft",
"campaign_id": "8304d4b0-90e0-4c58-ae3d-38807b23fd9c",
"created_at": "2023-02-14T09:18:48.318-05:00",
"html_url": "http://{{defaultHost}}/o/abc-company/campaigns/8304d4b0-90e0-4c58-ae3d-38807b23fd9c/screenshot_sets/e9b4c72e-7520-4e3f-a3e8-a092b927f0d4"
}
Disabled organizations
When an organization is disabled (i.e. it does not have an active subscription), the API will return a 403 Forbidden response:
{
"status": "failure",
"errors": {
"organization": ["Your organization is disabled. Upgrade to keep using the API: https://adreform.com/o/_/billing"]
}
}
The Campaign object
The campaign
object is used to tell us where to store the Ad and Screenshot data for the request. You must included either campaign.id
or campaign.name
in the request.
campaign.id
-> the Ad Reform ID for an existing Campaign. Use this if you know the specific ID for the campaign you want to use, otherwise usecampaign.name
.campaign.name
-> the name you want to use for the Campaign. If a Campaign already exists with this name, we'll use that, otherwise we'll create a new one with this value as the name.
The Ad object
The ad
object (within each object in the screenshot_requests
array) is used to indicate what ad data you want to use in the screenshots you're requesting. This can be entirely new ad data (i.e. an ad creative that does not yet exist in your Ad Reform account), or it can be the id
or lookup_key
pointing to an existing ad.
ad.id
-> the Ad Reform ID for an existing Ad in your account.ad.lookup_key
-> a unique ID for an Ad. If an Ad already exists with this key, we'll use that Ad, otherwise we'll create a new one with this value as thelookup_key
.ad.media
-> an object withtype
andcontent
keys that contains actual Ad creative data. .
The Media object
To create a new ad, provide ad creative content in the media
object (within the ad
object):
"ad": {
"media": {
"type": "url"
"content": "https://url-to-ad-creative-content.com"
}
}
Supported media types
Here are the supported type
values and some related content
examples:
html_tag
<img src="https://placehold.co/300x250" width="300" height="250" />
An HTML string containing ad creative content (often a <script>
tag or an <image>
tag)
url
The URL for an ad creative, such as an image, video, VAST tag, or HTML5 zip file
The Screenshots array
Within the screenshots
array, there will be a JSON object for each screenshot for the associated ad. Each object is composed of site
object and a device
object.
"screenshots": [
{
"device": {
"name": "desktop"
},
"site": {
"url": "https://www.adreform.com/"
}
}
]
The Site object
The Site
object in the screenshots
array must include a url
key.
site.url
-> the website URL
"site": {
"url": "https://www.adreform.com"
}
The Device object
The Device
object in the screenshots
array must include a name
key.
device.name
-> the device to use when generating the screenshot
"device": {
"name": "desktop"
}
Supported devices
Here's a list of supported device.name
values:
desktop
mobile
iphone
tablet
ipad
Apple iPad
Apple iPhone 5
Apple iPhone 6
Apple iPhone 6 Plus
Apple iPhone X
Apple iPhone 14 Pro Max
Google Nexus 10
Google Nexus 5
Google Nexus 6
Google Pixel 4
Samsung Galaxy S10
The Options object
You can use the options
object within a screenshot
object to specify additional settings.
Specifying which ad frames to use
You can use the options.ad.frames
array to specify which frame(s) of the ad to use within a screenshot:
"options": {
"ad": {
"frames": [
{ "marker": 0.5 },
{ "marker": 1.0 }
]
}
}
Each object in the frames
array should include a marker
, which should be a float
representing the timestamp (in seconds) where the frame should be captured. The marker
value must be between 0 and 30 seconds.
Example payload using options.ad.frames
options.ad.frames
"screenshots": [
{
"device": {
"name": "desktop"
},
"site": {
"url": "https://website-one.com"
},
"options": {
"ad": {
"frames": [
{ "marker": 0.5 },
{ "marker": 15.0 }
]
}
}
}
]
Example payload specifying frames with multiple screenshot
objects
screenshot
objects{
"screenshot_requests": [
{
"ad": {
"media": {
"type": "url",
"content": "https://url-to-ad-video-content.com"
}
},
"screenshots": [
{
"site": {
"url": "https://website-one.com"
},
"device": {
"name": "desktop"
},
"options": {
"ad": {
"frames": [
{ "marker": 0.0 },
{ "marker": 1.0 }
]
}
}
},
{
"site": {
"url": "https://website-two.com"
},
"device": {
"name": "mobile"
},
"options": {
"ad": {
"frames": [
{ "marker": 1.0 },
{ "marker": 2.0 }
]
}
}
}
]
}
]
}
In this example:
Since the
screenshot
objects are within the samead
object, we will merge the framemarker
valuesWe will generate 4 screenshots:
2 on
website-one.com
at frames0.0
and1.0
2 on
website-two.com
at frames1.0
and2.0
Last updated
Was this helpful?