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:

Launch UA expansion campaigns
Manage campaign spend and certain targeting settings
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	Retrieve, create, and modify campaigns

Rate limits and quotas

Quota	Limit
Requests per minute per REST method	1,000
Max campaigns enabled at one time	100
Max enabled creatives per campaign	100
Max creatives assembled daily	1,500
Max assets uploaded daily	1,500

Error handling

The API uses standard HTTP status codes.

Error code	Description
400	Bad Request
401	Missing or Invalid API Key
403	Access Denied
404	Not Found
429	Too Many Requests
500	Server Error
503	Service Unavailable

Sample workflows: Creating campaigns

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/campaigns`
Creatives	`https://cm-api.liftoff.io/v1/creatives`
Events	`https://cm-api.liftoff.io/v1/apps/{appId}/events`
Audiences	`https://cm-api.liftoff.io/v1/audiences`

Follow this sequence to launch your campaign. Only UA expansion campaigns are currently supported.

Upload assets
Assemble creatives
Create a campaign
Attach the creatives to the campaign
Enable the campaign

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

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:

Note that the following example shows the request and response when creating a VAST creative. Please refer to the NewCreativeBodyGeneral section of the API Reference for more details.

POST /v1/creatives

{
  "name": "SpringSale",
  "status": "PAUSED",
  "language": "en",
  "creativeType": "vast",
  "adSlotSize": "320x480",
  "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": "app_abc",
  "name": "SpringSale",
  "status": "PAUSED",
  "language": "en",
  "creativeType": "vast",
  "adSlotSize": "320x480",
  "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": "320x480",
      "vast": [
        {
          "videoAssetId": "ast_123",
          "endcardHtmlAssetId": null,
          "endcardImageAssetId": "ast_456"
        }
      ],
      "previewLink": "https://tre-preview.liftoff.io/preview/index.html?vm=true&creative=123456"
    }
  ]
}

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
	Full-screen (Image and video)	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
	Full-screen (Image and video)	Landscape	1024 x 768
	Banner (Image)		728 x 90
Native (Image)			1200 x 627

Create a campaign

Next, create the UA campaign that will host your creatives. Campaigns are created in a paused state by default.

You must provide the following fields: appId, clickTrackingUrl, spendCap, optimizationGoal, goalValue, and targeting.
Campaign budgets are set in USD, with daily limits and constraints (budget changes allowed only 3× per day, within ±50%)
A maximum of 100 campaigns can be enabled at once
Must have a daily spend target ≥ $500
Goal values are only for reference and do not affect performance or optimization

Example:

POST /v1/campaigns

{
  "appId": "app_abc",
  "name": "UA_Q2_CPI",
  "spendCap": 5000,
  "optimizationGoal": "CPA",
  "goalValue": 2.50,
  "optimizationFinalEventId": "12345",
  "demandProduct": "accelerate",
  "minOsVersion": "12.1.3",
  "clickTrackingUrl": "https://example.tracker.com/id12345?&c=${CAMPAIGN_NAME}&siteid=${APP_ID}&ad=${CREATIVE_NAME}&c_id=${CAMPAIGN_EXTERNAL_ID}&ad_id=${CREATIVE_EXTERNAL_ID}&click_lookback=7d&clickid=${TRACKING_TOKEN}&idfa=${IDFA}&sha1_idfa=${IDFA_SHA1}&ip=${DEVICE_IP}&ua=${DEVICE_USER_AGENT}&channel=${DEMAND_PRODUCT}&lang=${DEVICE_LANGUAGE}&os_version=${DEVICE_OS_VERSION}&model=${DEVICE_MODEL}",
  "pacingType": "daily",
  "targeting": {
    "countries": ["US", "CA"],
    "devices": ["mobile"],
    "excludedAudienceIds": ["A54BE3F"],
    "includedAudienceIds": ["B2D4F1D"]
  }
}

curl -X 'POST' \
  'https://cm-api.liftoff.io/v1/campaigns' \
  -u 'API_KEY:API_SECRET' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "appId": "app_abc",
  "name": "UA_Q2_CPI",
  "spendCap": 5000,
  "optimizationGoal": "CPA",
  "goalValue": 2.50,
  "optimizationFinalEventId": "12345",
  "demandProduct": "accelerate",
  "minOsVersion": "12.1.3",
  "clickTrackingUrl": "https://example.tracker.com/id12345?&c=${CAMPAIGN_NAME}&siteid=${APP_ID}&ad=${CREATIVE_NAME}&c_id=${CAMPAIGN_EXTERNAL_ID}&ad_id=${CREATIVE_EXTERNAL_ID}&click_lookback=7d&clickid=${TRACKING_TOKEN}&idfa=${IDFA}&sha1_idfa=${IDFA_SHA1}&ip=${DEVICE_IP}&ua=${DEVICE_USER_AGENT}&channel=${DEMAND_PRODUCT}&lang=${DEVICE_LANGUAGE}&os_version=${DEVICE_OS_VERSION}&model=${DEVICE_MODEL}",
  "pacingType": "daily",
  "targeting": {
    "countries": ["US", "CA"],
    "devices": ["mobile"],
    "excludedAudienceIds": ["A54BE3F"],
    "includedAudienceIds": ["B2D4F1D"]
    }
  }'

Response:

{
  "id": "asd123"
}

Attach the creatives to the campaign

Once your campaign is created, you can attach your creatives.

Minimum of 1 enabled creative to deliver
Maximum of 100 enabled creatives per campaign
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 /v1/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"}'

Enable the campaign

Finally, set the campaign status to enabled.

Must have a daily spend target ≥ $500
Must have ≥ 1 enabled creative attached

Example:

POST /v1/campaigns/{campaignId}/status

{
  "status": "ENABLED"
}

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

Examples: Editing campaign spend

Must have a daily spend target ≥ $500.
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 /v1/campaigns/{campaignId}/spendCaps/daily

{
"value": 7500
}

Schedule future spend changes

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

Example:

POST /v1/campaigns/{campaignId}/spendCaps/schedule

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

Cancel scheduled spend changes

Example:

POST /v1/campaigns/{campaignId}/spendCaps/cancel

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

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 /v1/campaigns/{campaignId}/status

Example:

POST /v1/campaigns/{campaignId}/status

{
  "status": "ENABLED"
}

Examples: Editing campaign targeting

This section walks through how to edit settings for existing campaigns using the POST /v1/campaigns/{campaignId} endpoint. This endpoint works similarly to the campaign creation endpoint in terms of the data it takes in the request body. The only difference is that a campaign ID needs to be provided in the URL, and only the following settings can be edited.

When targeting settings are updated, pacing may temporarily adjust as the system optimizes to the new configuration to best deliver performance. While delivery typically stabilizes within a few hours, to minimize variability, we recommend making changes earlier in the day.

Settings

Optimization goal: which metric the campaign optimizes for
Optimization final event ID: the target event for CPA campaigns
Goal value: the value associated with the optimization goal
Country: which countries the campaign is targeting

Optimization goal, values, and final event

optimizationGoal
- Decides which metric the campaign optimizes for
- Possible values: CPI, CPA, ROAS
- When using CPA, an optimizationFinalEventId must also be added
  - The target event that the campaign is optimizing towards
- Changes to optimization goals or final event selection may impact delivery behavior as the system adjusts to the updated objective
goalValue
- The value associated with the optimization goal
- Informational only and does not affect campaign optimization or performance
- For CPA and CPI goals, the target value is in USD
- For ROAS goals the target value is % return

Field	Type	Allowed values	Example
optimizationGoal	string	CPI, CPA, ROAS	CPI
goalValue	number	-	5.5
optimizationFinalEventId	string	-	3082534

Example:

POST /v1/campaigns/{campaignId}

{
  "optimizationGoal": "CPA",
  "goalValue": 7.3,
  "optimizationFinalEventId": "a1b2c3"
}

Country targeting

Which countries the campaign is targeting
Note that expanding or narrowing targeting may affect available inventory and delivery behavior as the system adjusts to the updated targeting

Field	Type	Allowed values	Example
countries	string[]	List of two-letter country codes	US, CA

Example of updating the targeted country:

POST /v1/campaigns/{campaignId}

{
  "targeting": { "countries": ["US", "CA"] }
}

Support

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

Campaign Management API (Closed Beta)

Authentication​

API structure​

Rate limits and quotas​

Error handling​

Sample workflows: Creating campaigns​

Examples: Editing campaign spend​

Examples: Editing campaign state​

Examples: Editing campaign targeting​

Optimization goal, values, and final event​

Country targeting​

Support​

Authentication

API structure

Rate limits and quotas

Error handling

Sample workflows: Creating campaigns

Examples: Editing campaign spend

Examples: Editing campaign state

Examples: Editing campaign targeting

Optimization goal, values, and final event

Country targeting

Support