Create a Screenshot Request

Creates a Screenshot Request

post

Creates a screenshot request from provided data.

Important Validation Rules:

Each lookup_key must be unique within the same API request

Authorizations

Path parameters

organization_slugstringRequired

Organization slug

Example: abc-company

Header parameters

AuthorizationstringOptional

Authorization

Body

instructionsstringOptionalExample: Please take a screenshot of the ad on the homepage of the site

Responses

202

Accepted

application/json

403

Forbidden

application/json

422

Unprocessable Entity

application/json

post

/api/v1/orgs/{organization_slug}/screenshot_requests

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.

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.

Note: Campaign names cannot be longer than 250 characters. A campaign.name longer than 250 characters will be truncated automatically.

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.

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.

Example payload using `ad.lookup_key`

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

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

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

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:

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.

If options.ad.frames is an empty array (i.e. no frames are specified), we will use our default logic for capturing the ad.

Example payload using `options.ad.frames`

"screenshots": [
  {
    "device": {
      "name": "desktop"
    },
    "site": {
      "url": "https://website-one.com"
    },
    "options": {
      "ad": {
        "frames": [
          { "marker": 0.5 },
          { "marker": 15.0 }
        ]
      }
    }
  }
]

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 markers into a single, de-duplicated set.

Example payload specifying frames with multiple `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 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

Last updated 1 month ago

Was this helpful?

Creates a Screenshot Request

Disabled organizations

The Campaign object

campaign.id

campaign.name

The Ad object

ad.id

ad.lookup_key

Example payload using ad.lookup_key

Example incorrect payload – duplicate ad.lookup_key across entries (rejected)

ad.media

The Media object

Supported media types

The Screenshots array

The Site object

site.url

The Device object

device.name

Supported devices

The Options object

Specifying which ad frames to use

Example payload using options.ad.frames

Example payload specifying frames with multiple screenshot objects

`campaign.id`

`campaign.name`

`ad.id`

`ad.lookup_key`

Example payload using `ad.lookup_key`

Example incorrect payload – duplicate `ad.lookup_key` across entries (rejected)

`ad.media`

`site.url`

`device.name`

Example payload using `options.ad.frames`

Example payload specifying frames with multiple `screenshot` objects