Campaign Management API (Closed Beta)

The Campaign Management API is currently in closed beta and available to select customers. We are continuing to enhance features and performance ahead of general availability. As this API is in beta, certain functionality and limits may evolve. If interested, please contact your Account Manager to learn more.

The Campaign Management API allows you to programmatically manage your campaigns and creatives. With the Campaign Management API, you can:

• Manage campaign spend and state
• Upload assets and assemble creatives
• Manage creative state and attachment

Authentication

The API uses HTTP Basic authentication. To authenticate, send your API token in the Authorization header as a base64-encoded string. For example:

Authorization: Basic <base64(ApiKey:ApiSecret)>

• ApiKey is your Liftoff API Key
• ApiSecret is your Liftoff API Secret
• The value is the Base64 encoding of the string ApiKey:ApiSecret

API structure

You can explore all available endpoints in the API Reference and Sandbox. All API URLs start with https://cm-api.liftoff.io/v1, use standard REST patterns, and return JSON. Different endpoints can be called by appending to the base url. Available endpoints are described in the table below:

Endpoints	Description
/apps	Retrieve app list and metadata
/assets	Upload and manage assets
/creatives	Assemble creatives
/campaigns	Modify campaigns

Rate limits and quotas

Endpoints	Limit
Max campaigns enabled at one time	100
Max enabled creatives per campaign	100
Max creatives assembled daily	1500
Max assets uploaded daily	1500

Error handling

The API uses standard HTTP status codes.

Error code	Description
400	Request
403	Access Denied
404	Not Found
429	Too Many Requests
500	Server Error
503	Service Unavailable

Sample workflows: Uploading creatives

Before you start, explore the various entities associated with your account via the following endpoints.

Entities	URL
Apps	https://cm-api.liftoff.io/v1/apps
Campaigns	https://cm-api.liftoff.io/v1/apps/{appId}/campaigns
Creatives	https://data.liftoff.io/api/v1/creatives
Events	https://data.liftoff.io/api/v1/events
Audiences	https://analytics.liftoff.io/audiences/v1/list

Follow this sequence to upload, assemble, and attach creatives to campaigns.

1. Upload assets
2. Assemble creatives
3. Attach the creatives

---

1. Upload assets

Begin by uploading the media files (images or videos) you want to use in your creatives. Each uploaded asset receives a unique assetId, which is later referenced when assembling creatives.

• You can upload up to 1,500 assets daily
• Maximum file size for image is 10MB
• Maximum video duration is 180 seconds
• Supported file types:
  • Images: JPEG, PNG, WebP, GIF
  • Videos: MP4, QuickTime (MOV), WebM

Example:

POST /v1/assets

curl -X POST 'https://cm-api.liftoff.io/v1/assets' \
  -u 'API_KEY:API_SECRET' \
  -H 'Accept: application/json' \
  -F 'file=@/dir/test.mp4;type=video/mp4;filename=test.mp4'

Response:

{
  "id": "123abc",
  "mediaType": "video",
  "publicUrl": "https://cdn.liftoff.io/assets/ast_123.video",
  "name": "ast_123.video"
}

2. Assemble creatives

You can assemble creatives using uploaded assets. Each creative ties an asset ID to metadata. All creative types require the following information, and some fields are specific to their creative type. Please view the API Reference for more details.

• A maximum of 1,500 creatives can be assembled daily
• Required for all creatives: app ID, name, status, creative type, ad slot size, language
  • VAST creatives
    • Video asset ID
    • Endcard asset ID
  • Native creatives
    • Image asset ID
    • Title
    • Description
    • Optional: icon asset ID, CTA text translation
  • Image creatives
    • Image asset ID

Example:

POST /v1/creatives

{
  "name": "SpringSale",
  "status": "PAUSED",
  "language": "en",
  "creativeType": "vast",
  "adSlotSize": "1200x628",
  "videoAssetId": "ast_123",
  "endcardAssetId": "ast_456",
  "appId": "app_abc"
}

curl -X 'POST' \
  'https://cm-api.liftoff.io/v1/creatives' \
  -u 'API_KEY:API_SECRET' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "appId": "123asd",
  "name": "SpringSale",
  "status": "PAUSED",
  "language": "en",
  "creativeType": "vast",
  "adSlotSize": "1200x628",
  "videoAssetId": "ast_123",
  "endcardAssetId": "ast_456"}'

Response:

{
 "creatives": [
    {
      "id": "123456",
      "name": "SpringSale",
      "status": "PAUSED",
      "creativeType": "vast",
      "createdAt": "2025-09-27T22:10:43.034Z",
      "language": "en",
      "adSlotSize": "1200x628",
    }
  ],
  "vast": [
    {
      "videoAssetId": "ast_123",
      "endcardAssetId": "ast_456",
    }
  ]
}

Ad slot sizes are required to assemble creatives. Declare the ad slot size to include Liftoff tablet or phone sizes:

Device	Placements	Orientation	Ad slot size
Phone	Full-screen (Image and video)	Portrait	320 x 480
		Landscape	480 x 320
	Half-screen (Image and Video)		300 x 250
	Banner (Image)		320 x 50
Tablet	Full-screen (Image and video)	Portrait	768 x 1024
		Landscape	1024 x 768
	Banner (Image)		728 x 90
Native (Image)			1200 x 627

3. Attach creatives to campaigns

Note that adding a new creative format to an enabled campaign may affect available inventory and delivery behavior as the system adjusts to the updated targeting.

Example:

POST /campaigns/{campaignId}/creatives/add

{
  "creativeId": "123abc"
}

curl -X 'POST' \
  'https://cm-api.liftoff.io/v1/campaigns/{campaignId}/creatives/add' \
  -u 'API_KEY:API_SECRET' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"creativeId": "123abc"}'

Examples: Editing campaign spend

• Spend targets can only be changed 3 times within a 24 hour period.
• Each of these spend changes must be +/- 50% of the previous value to protect pacing.
• Changes can only be made within the first 12 hours of the day based on your billing timezone, as large or frequent spend changes may impact pacing and delivery for the remainder of the day.

Update spend targets

Example:

POST /campaigns/{campaignId}/spendCaps/daily

{
"value": 7500
}

Response:

{
  "campaignId": "123456",
  "dailySpendCap": 7500,
  "updatedAt": "2026-02-13T19:22:31Z"
}

Schedule future spend changes

Scheduled changes will apply at midnight on the specified date based on your billing timezone.

Example:

POST /campaigns/{campaignId}/spendCaps/schedule

{
  "date": "2026-03-01",
  "value": 10000
}

Response:

{
  "campaignId": "123456",
  "scheduledChange": {
    "date": "2026-03-01",
    "value": 10000
  }
}

Cancel scheduled spend changes

Example:

POST /campaigns/{campaignId}/spendCaps/cancel

{
  "date": "2026-03-01",
  "after": false
}

Response:

{
  "campaignId": "123456",
  "canceledFromDate": "2026-03-01"
}

Examples: Editing campaign state

You can pause or enable campaigns using the endpoint below. To verify correct settings, you cannot enable campaigns that have been paused for more than 30 days; to adjust those, reach out to your Account Manager.

Endpoint: POST /campaigns/{campaignId}/status

Example:

{
  "status": "ACTIVE"
}

Response:

{
  "campaignId": "123456",
  "status": "ACTIVE",
  "updatedAt": "2026-02-13T19:35:02Z"
}

Support

Please contact your Liftoff account team if you have feedback or need support.