Ctrlk
Help CenterLog in
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Create an Ad

This feature is currently in beta. Contact support@adreform.com if you're interested in trying the beta.

Creates an Ad

post

Ad with matching lookup_key already exists. Returns existing ad without modification.

Authorizations
AuthorizationstringRequired

API key necessary to authenticate API requests

Path parameters
organization_slugstringRequired

Organization slug

Example: abc-company
Header parameters
AuthorizationstringOptional

Bearer token for API authentication

Body
Responses
200

OK - Existing ad returned

application/json
typestringOptionalExample: ad
idstring · uuidOptionalExample: e9b4c72e-7520-4e3f-a3e8-a092b927f0d4
namestringOptionalExample: My Ad
lookup_keystring · nullableOptionalExample: my-internal-key-0001
statusstring · enumOptionalExample: uploadedPossible values:
categorystring · nullableOptionalExample: display
kindstringOptional

Media type: url or html_tag

Example: url
campaign_idstring · uuidOptionalExample: 8304d4b0-90e0-4c58-ae3d-38807b23fd9c
created_atstring · date-timeOptionalExample: 2023-02-14T09:18:48.318-05:00
html_urlstring · uriOptionalExample: https://app.adreform.com/o/abc-company/campaigns/8304d4b0/ads/e9b4c72e
post/api/v1/orgs/{organization_slug}/ads
POST /api/v1/orgs/{organization_slug}/ads HTTP/1.1
Host: app.adreform.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 349

{
  "campaign": {
    "id": "8304d4b0-90e0-4c58-ae3d-38807b23fd9c",
    "name": "New Campaign - Via API"
  },
  "ad": {
    "name": "My Ad",
    "lookup_key": "my-internal-key-0001",
    "media": {
      "type": "url",
      "content": "https://placehold.co/300x250"
    }
  },
  "subscribers": [
    {
      "webhook": {
        "url": "https://webhook.site/callback"
      },
      "s3": {
        "bucket": "my-bucket",
        "region": "us-east-1",
        "key_prefix": "ads/"
      }
    }
  ]
}
{
  "type": "ad",
  "id": "e9b4c72e-7520-4e3f-a3e8-a092b927f0d4",
  "name": "My Ad",
  "lookup_key": "my-internal-key-0001",
  "status": "uploaded",
  "category": "display",
  "kind": "url",
  "campaign_id": "8304d4b0-90e0-4c58-ae3d-38807b23fd9c",
  "created_at": "2023-02-14T09:18:48.318-05:00",
  "html_url": "https://app.adreform.com/o/abc-company/campaigns/8304d4b0/ads/e9b4c72e"
}

Overview

This endpoint allows you to create ads independently from the screenshot request workflow. This is useful when you want to:

  • Pre-create ads before requesting screenshots

  • Manage ad inventory separately from screenshot generation

  • Build integrations that separate ad upload from screenshot workflows

Idempotent Behavior

This endpoint is fully idempotent when using lookup_key:

  • If an ad with the specified lookup_key already exists in the campaign, we'll return the existing ad with a 200 OK status

  • The media in the request is ignored when returning an existing ad

  • New ads are created with a 201 Created status

This makes it safe to retry requests without risking duplicate ad creation.

Disabled organizations

When an organization is disabled (i.e. it does not have an active subscription), the API will return a 403 Forbidden response:

The Campaign object

The campaign object tells us where to store the ad. You must include either campaign.id or campaign.name in the request.

Using campaign.name is the most common approach, 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.

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.

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 contains the ad creative data.

ad.lookup_key (optional)

A unique identifier for this ad. Use this to make requests idempotent - if an ad already exists with this lookup_key in the campaign, we'll return that ad instead of creating a new one.

ad.name (optional)

A human-readable name for the ad.

ad.media (required for new ads)

The ad creative content. Contains:

  • type: Either "url" or "html_tag"

  • content: The URL or HTML tag content

The html_tag content cannot exceed 1MB in size.

Media Types

URL (type: "url")

Use this for ad tag URLs that resolve to a creative. The URL will be fetched and rendered to capture the ad preview.

HTML Tag (type: "html_tag")

Use this for raw HTML ad tags (like script tags or iframe embeds).

Subscribers (optional)

You can optionally subscribe to notifications when the ad preview is captured by including a subscribers array.

Webhook Subscriber

Receive an ad.uploaded webhook event when the ad preview is ready:

Webhook subscribers only receive notifications when a new ad is created (201 Created response). If an existing ad is returned via lookup_key (200 OK response), no webhook is sent. The existing ad data is returned in the API response, so you can use it directly.

S3 Subscriber

Push the ad preview image to your S3 bucket when ready:

S3 subscriptions require an S3 connector to be configured for your organization.

Response

Success Response (201 Created)

For newly created ads:

Success Response (200 OK)

When an existing ad is returned via lookup_key, the response contains the ad's current state:

Status Values

Status
Description

pending

Ad created, preview capture in progress

uploaded

Preview capture completed successfully

not_found

Media URL could not be found

net_read_timeout

Network timeout during capture

generic_error

Other capture error

nothing_to_capture

The creative has no visual content, so there is nothing to screenshot

Error Response (422 Unprocessable Entity)

Example Requests

Create ad with URL media

Create ad with HTML tag and webhook subscriber

Idempotent request (returns existing ad)

Last updated