Create a Campaign

Call POST /v1/ads/create. Zernio publishes a promoted-only post (hidden from the organic timeline, shown only as an ad) as the ad account's full promotable user. It then creates the campaign, line item and promoted post around it.

body carries the post text, at most 280 characters. A linkUrl on its own is appended to the text, and X counts it as about 24 characters because it shortens the link. Add imageUrl and headline to show it as a website card instead.

description, video and callToAction have no slot on X and return 400. To run an X ad with a video, promote a post that already carries it, within X's media limits.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: created } = await zernio.adcampaigns.createStandaloneAd({
  body: {
    accountId: '66b2e19d8c3f5a7e9d0b1c2d',
    adAccountId: '18ce54d4x5t',
    name: 'Q2 product awareness',
    goal: 'awareness',
    budgetAmount: 75,
    budgetType: 'daily',
    body: 'Ship faster with platform engineering done right.',
    linkUrl: 'https://example.com/platform',
    countries: ['US']
  }
});

console.log(created.ad.platformAdSetId);

Response (201):

{
  "ad": {
    "_id": "66f0a1b2c3d4e5f6a7b8c9d0",
    "name": "Q2 product awareness",
    "platform": "twitter",
    "status": "pending_review",
    "adType": "standalone",
    "goal": "awareness",
    "budget": { "amount": 75, "type": "daily" },
    "platformAdId": "5gzhb",
    "platformCampaignId": "f4x8j",
    "platformAdSetId": "9r2mv"
  },
  "message": "Ad created"
}

budgetAmount is in whole currency units of the ad account, so 75 is $75.00 on a USD account.

budgetType is daily or lifetime and lands on the line item. A lifetime budget needs endDate, and startDate defaults to now.

platformAdSetId is the X line item. Every sample below reuses the zernio and client constructors from this one.

Website card

imageUrl, headline and linkUrl together build an X website card: the image, the headline as its title (at most 70 characters) and the destination under the post. The URL is then not added to the post text, so body keeps all 280 characters.

imageUrl or headline without the other two returns 400 with code missing_required_field naming the missing one. A linkUrl alone is valid: it makes a plain post with the link appended.

Zernio downloads imageUrl and uploads it to X, so it must be a public URL.

curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "adAccountId": "18ce54d4x5t",
    "name": "Q2 platform launch",
    "goal": "traffic",
    "budgetAmount": 500,
    "budgetType": "lifetime",
    "startDate": "2027-01-04T00:00:00+01:00",
    "endDate": "2027-01-31T23:59:59+01:00",
    "body": "Ship faster with platform engineering done right.",
    "imageUrl": "https://example.com/images/platform-card.png",
    "headline": "Platform engineering, done right",
    "linkUrl": "https://example.com/platform",
    "countries": ["US"]
  }'

startDate and endDate take ISO 8601 date-times with an offset, as above. A value without an offset, date-only included, is read in the ad account's timezone, and a date-only endDate runs to 23:59:59 local.

Targeting fields

countries, regions, cities, metros, zips and interests apply on X.

Take the geo keys and interest ids from GET /v1/ads/targeting/search with dimension=geo or dimension=interest on the X connection.

They are X's own targeting values, so a key from another platform does not work.

incomeTier, customLocations and behaviors are rejected (X removed behavior targeting from its Ads API).

audienceInclude and audienceExclude take the X custom audience id of a Tailored Audience.