# Create a Screenshot Request {% openapi src="" path="/api/v1/orgs/{organization\_slug}/screenshot\_requests" method="post" %} [ad-reform-swagger.yaml](https://2718083151-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWXKnh5nreVaQejzmqBUM%2Fuploads%2Fgit-blob-62087cc88de5585e2f431015233e37e65369350e%2Fad-reform-swagger.yaml?alt=media) {% endopenapi %} ## Disabled organizations When an organization is disabled (i.e. it does not have an active subscription), the API will return a 403 Forbidden response: ```json { "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. {% hint style="info" %} Using `campaign.name` is the most common, as we will find *or* create a Campaign using this key {% endhint %} ### `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 use `campaign.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. {% hint style="info" %} Note: Campaign names cannot be longer than 250 characters. A `campaign.name` longer than 250 characters will be truncated automatically. {% endhint %} ## 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 the `lookup_key`. {% hint style="info" %} Within a single API request, each `ad.lookup_key` must be unique across all entries in `screenshot_requests`. If you need multiple screenshots for the same ad, specify them within the `ad` object as multiple screenshots in the `screenshots` array. {% endhint %} ### `ad.name` An optional name for the ad. This is used when creating a new ad — either by providing `ad.media` alone, or by providing `ad.media` with a `lookup_key` that doesn't match any existing ad. When referencing an **existing** ad by `id` or `lookup_key`, this field is ignored and the existing ad's name is preserved. {% hint style="info" %} The `ad.name` field has a maximum length of 255 characters. {% endhint %} #### Example payload using `ad.lookup_key` ```json { "screenshot_requests": [ { "ad": { "lookup_key": "key-123", "media": { "type": "url", "content": "https://example.com/ad.png" } }, "screenshots": [ { "site": { "url": "https://website-one.com" }, "device": { "name": "desktop" } }, { "site": { "url": "https://website-two.com" }, "device": { "name": "mobile" } } ] } ] } ``` #### Example incorrect payload – duplicate `ad.lookup_key` across entries (rejected) ```json { "screenshot_requests": [ { "ad": { "lookup_key": "key-123", "media": { "type": "url", "content": "https://example.com/ad.png" } }, "screenshots": [ { "site": { "url": "https://website-one.com" }, "device": { "name": "desktop" } } ] }, { "ad": { "lookup_key": "key-123", "media": { "type": "url", "content": "https://example.com/ad.png" } }, "screenshots": [ { "site": { "url": "https://website-two.com" }, "device": { "name": "mobile" } } ] } ] } ``` ### `ad.media` An object with `type` and `content` keys that contains actual Ad creative data. {% hint style="info" %} You can use both `ad.media` (to send in raw ad data) and `ad.lookup_key` together in a request, so future requests with the same `lookup_key` will be associated to the same Ad in Ad Reform {% endhint %} #### **The Media object** To create a new ad, provide ad creative content in the `media` object (within the `ad` object): ```json "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:
TypeContentDescription
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

Image: https://placehold.co/300x250


Video: https://www.w3schools.com/tags/movie.mp4

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. ```json "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. ```json "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. ```json "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: ```json "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. {% hint style="info" %} If `options.ad.frames` is an empty array (i.e. no frames are specified), we will use our default logic for capturing the ad. {% endhint %} #### Example payload using `options.ad.frames` ```json "screenshots": [ { "device": { "name": "desktop" }, "site": { "url": "https://website-one.com" }, "options": { "ad": { "frames": [ { "marker": 0.5 }, { "marker": 15.0 } ] } } } ] ``` {% hint style="info" %} If a request payload includes multiple `screenshot` objects within a single `ad` object, and these `screenshot` objects specify `options.ad.frames`, we will merge all frame `marker`s into a single, de-duplicated set. {% endhint %} #### Example payload specifying frames with multiple `screenshot` objects ```json { "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 same `ad` object, we will merge the frame `marker` values * We will generate 4 screenshots: * 2 on `website-one.com` at frames `0.0` and `1.0` * 2 on `website-two.com` at frames `1.0` and `2.0`