Create an Ad

This feature is currently in beta. Contact [email protected] if you're interested in trying the beta.

Create an Ad

post

Creates an ad independently from the screenshot request workflow.

This endpoint is idempotent when using lookup_key:

• If an ad with the specified lookup_key already exists in the campaign, returns the existing ad with 200 OK
• New ads are created with 201 Created

Authorizations

Bearer

AuthorizationstringRequired

API key necessary to authenticate API requests

Path parameters

organization_slugstringRequired

Organization slug

Example: abc-company

Header parameters

AuthorizationstringOptional

Authorization

Body

application/json

Responses

200

OK (existing ad returned)

application/json

201

Created

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

422

Unprocessable Entity

application/json

post

/api/v1/orgs/{organization_slug}/ads

HTTPcURLJavaScriptPython

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

{
  "campaign": {
    "id": "8304d4b0-90e0-4c58-ae3d-38807b23fd9c",
    "name": "New Campaign - Via API"
  },
  "ad": {
    "lookup_key": "my-internal-key-0001",
    "name": "Banner Ad 300x250",
    "media": {
      "type": "html_tag",
      "content": "<img src=\"https://picsum.photos/300/250\"/>"
    }
  },
  "subscribers": [
    {
      "webhook": {
        "url": "https://webhook.site/ae28ba3d-7c83-4a52-a0e4-5925f76d3a14"
      },
      "s3": {
        "bucket": "my-bucket",
        "region": "us-east-1",
        "key_prefix": "ads/"
      }
    }
  ]
}

{
  "type": "ad",
  "id": "e9b4c72e-7520-4e3f-a3e8-a092b927f0d4",
  "name": "Banner Ad 300x250",
  "lookup_key": "my-internal-key-0001",
  "status": "pending",
  "category": "display",
  "kind": "html_tag",
  "campaign_id": "8304d4b0-90e0-4c58-ae3d-38807b23fd9c",
  "created_at": "2026-01-17T10:30:00-05:00",
  "html_url": "https://app.adreform.com/o/abc-company/campaigns/8304d4b0-90e0-4c58-ae3d-38807b23fd9c/ads/e9b4c72e-7520-4e3f-a3e8-a092b927f0d4"
}

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:

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

{
  "media": {
    "type": "url",
    "content": "https://example.com/ad-tag?size=300x250"
  }
}

HTML Tag (type: "html_tag")

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

{
  "media": {
    "type": "html_tag",
    "content": "<script src=\"https://example.com/ad.js\"></script>"
  }
}

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:

{
  "subscribers": [
    {
      "webhook": {
        "url": "https://your-endpoint.com/webhooks"
      }
    }
  ]
}

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:

{
  "subscribers": [
    {
      "s3": {
        "bucket": "your-bucket-name",
        "region": "us-east-1",
        "key_prefix": "ads/"
      }
    }
  ]
}

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

Response

Success Response (201 Created)

For newly created ads:

{
  "type": "ad",
  "id": "uuid-of-created-ad",
  "name": "Ad Name",
  "lookup_key": "your-lookup-key",
  "status": "pending",
  "category": "display",
  "kind": "url",
  "campaign_id": "uuid-of-campaign",
  "created_at": "2026-01-17T10:30:00Z",
  "html_url": "https://app.adreform.com/o/your-org/campaigns/uuid/ads/uuid"
}

Success Response (200 OK)

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

{
  "type": "ad",
  "id": "uuid-of-existing-ad",
  "name": "Ad Name",
  "lookup_key": "your-lookup-key",
  "status": "uploaded",
  "category": "display",
  "kind": "url",
  "campaign_id": "uuid-of-campaign",
  "created_at": "2026-01-15T10:30:00Z",
  "html_url": "https://app.adreform.com/o/your-org/campaigns/uuid/ads/uuid"
}

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

Error Response (422 Unprocessable Entity)

{
  "status": "failure",
  "errors": {
    "media.content": ["exceeds maximum size of 1MB"]
  }
}

Example Requests

Create ad with URL media

curl -X POST "https://app.adreform.com/api/v1/orgs/your-org/ads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": {
      "name": "Q1 2026 Campaign"
    },
    "ad": {
      "name": "Banner 300x250",
      "lookup_key": "banner-300x250-v1",
      "media": {
        "type": "url",
        "content": "https://example.com/ads/banner.png"
      }
    }
  }'

Create ad with HTML tag and webhook subscriber

curl -X POST "https://app.adreform.com/api/v1/orgs/your-org/ads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": {
      "name": "Q1 2026 Campaign"
    },
    "ad": {
      "name": "Rich Media Ad",
      "media": {
        "type": "html_tag",
        "content": "<script src=\"https://example.com/rich-media.js\"></script>"
      }
    },
    "subscribers": [
      {
        "webhook": {
          "url": "https://your-endpoint.com/ad-webhook"
        }
      }
    ]
  }'

Idempotent request (returns existing ad)

# First request creates the ad (201 Created)
curl -X POST "https://app.adreform.com/api/v1/orgs/your-org/ads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": {"name": "My Campaign"},
    "ad": {
      "lookup_key": "my-unique-key",
      "media": {"type": "url", "content": "https://example.com/ad.png"}
    }
  }'

# Retry request returns existing ad (200 OK)
curl -X POST "https://app.adreform.com/api/v1/orgs/your-org/ads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": {"name": "My Campaign"},
    "ad": {
      "lookup_key": "my-unique-key",
      "media": {"type": "url", "content": "https://different-url.com"}
    }
  }'
# ^ Returns the existing ad, ignores the different media