Create a Screenshot Request

Creates a Screenshot Request

Creates a screenshot request from provided data

POSThttps://app.adreform.com/api/v1/orgs/{organization_slug}/screenshot_requests

Authorization

Bearer

Path parameters

organization_slug*string

Organization slug

Example: "abc-company"

Header parameters

Body

application/json

Screenshot request

campaign*object

anyany

screenshot_requests*array of object

subscribers*array of object

instructionsstring

Example: "Please take a screenshot of the ad on the homepage of the site"

Response

202422

Accepted

Body

application/json

typestring

Example: "screenshot_set"

idstring

Example: "e9b4c72e-7520-4e3f-a3e8-a092b927f0d4"

statusstring

Example: "draft"

campaign_idstring

Example: "8304d4b0-90e0-4c58-ae3d-38807b23fd9c"

created_atdateTime

Example: "2023-02-14T09:18:48.318-05:00"

html_urlstring

Example: "http://{{defaultHost}}/o/abc-company/campaigns/8304d4b0-90e0-4c58-ae3d-38807b23fd9c/screenshot_sets/e9b4c72e-7520-4e3f-a3e8-a092b927f0d4"

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://app.adreform.com/api/v1/orgs/{organization_slug}/screenshot_requests', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <apiKey>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "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"
    }),
});
const data = await response.json();

Response

202422

{
  "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"
}

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.

Using campaign.name is the most common, as we will find or create a Campaign using this key

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

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.

• ad.media -> an object with type and content keys that contains actual Ad creative data. .

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

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:

Type	Content	Description
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.

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

• mobile

• iphone

• tablet

• ipad

• Apple iPad

• Apple iPhone 5

• Apple iPhone 6

• Apple iPhone 6 Plus

• Apple iPhone X

• Desktop

• Google Nexus 10

• Google Nexus 5

• Google Nexus 6

• Google Pixel 4

• Samsung Galaxy S10