Create an Ad

This feature is currently in beta. Contact [email protected] 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

201

Created

application/json

401

Unauthorized

403

Forbidden

422

Unprocessable Entity

application/json

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:

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

Last updated 1 month ago

hashtagCreates an Ad

hashtagOverview

hashtagIdempotent Behavior

hashtagDisabled organizations

hashtagThe Campaign object

hashtagcampaign.id

hashtagcampaign.name

hashtagThe Ad object

hashtagad.lookup_key (optional)

hashtagad.name (optional)

hashtagad.media (required for new ads)

hashtagMedia Types

hashtagURL (type: "url")

hashtagHTML Tag (type: "html_tag")

hashtagSubscribers (optional)

hashtagWebhook Subscriber

hashtagS3 Subscriber

hashtagResponse

hashtagSuccess Response (201 Created)

hashtagSuccess Response (200 OK)

hashtagStatus Values

hashtagError Response (422 Unprocessable Entity)

hashtagExample Requests

hashtagCreate ad with URL media

hashtagCreate ad with HTML tag and webhook subscriber

hashtagIdempotent request (returns existing ad)

Creates an Ad

Overview

Idempotent Behavior

Disabled organizations

The Campaign object

`campaign.id`

`campaign.name`

The Ad object

`ad.lookup_key` (optional)

`ad.name` (optional)

`ad.media` (required for new ads)

Media Types

URL (`type: "url"`)

HTML Tag (`type: "html_tag"`)

Subscribers (optional)

Webhook Subscriber

S3 Subscriber

Response

Success Response (201 Created)

Success Response (200 OK)

Status Values

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)