Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
idempotencyKey
string<uuid>
required
matchToken
string
required
projectId
string<uuid>
required
name
string
required
Required string length: 1 - 255
destinationUrl
string
required

Where the ad sends the reader. May carry placeholders that are substituted per placement, so the advertiser's own analytics can tell campaigns and channels apart under the parameter names his reporting already reads: {campaign} becomes the campaign's uuid, {channel} the handle of the channel that published the post (no @, lower case), {platform} the platform in lower case. They may sit anywhere in the URL, query string or path alike, including a bot deeplink payload — https://t.me/mybot?start={campaign}-{channel}. Names are case-insensitive and are stored lowercased, so the value returned by the API may differ from the one sent in exactly that way. Any OTHER {name} is rejected with a 400: an unknown placeholder cannot be filled in and would reach the published post as literal text. Deliberately NOT validated as a URI — a URL carrying a placeholder is not a well-formed one. Example: https://mysite.com/landing?utm_campaign={campaign}&utm_source={channel}

Required string length: 1 - 2048
adCopy
string
required

The ad text as markup, written exactly as ValidateAdCopyRequest.text describes it. Create applies the very same rules POST /api/v1/campaigns/ad-copy/validate applies, so a text that validates is a text that creates and there is no second verdict to discover here. Two of those rules decide most refusals: the text must carry at least one {these words are the link}, and it must contain no web address at all beyond one on the advertiser's own domain — the destination is attached to the {...} per placement and never written into the text. A refusal is a 400 whose message lists every problem with the span of the markup it occupies. The cap here is a bound on request size, an order of magnitude above any text that could pass the 700-character visible limit.

Maximum string length: 8000
platform
enum<string>
required
Available options:
TELEGRAM
distributionType
enum<string>
required
Available options:
RECOMMENDED,
MANUAL
mediaAssetIds
string<uuid>[]
required
Required array length: 1 - 3 elements
budget
string
required
Pattern: ^-?\d+(\.\d{1,6})?$
Example:

"125.500000"

startsAt
string<date>
required
endsAt
string<date>
required
dailyDistribution
object[]
required
approvalMode
enum<string>
required
Available options:
OPERATOR,
USER
objective
enum<string> | null
Available options:
AWARENESS,
TRAFFIC,
CONVERSIONS,
APP_INSTALLS
creativeChangesAllowed
boolean | null

Whether a channel manager may propose his own wording of the ad text (a human then approves or rejects it). Absent defaults to true, so deals are not lost over trivial edits.

excludedChannelIds
integer<int64>[] | null

Channels from the previewed match set the advertiser struck off while approving the list. They become neither placements nor part of the queue behind them, so the campaign can never come back to one of them later. Ids that are not in the previewed set are ignored. Rejected with 400 only if nothing at all is left after the strike-outs.

Response

Created

id
string<uuid>
required
projectId
string<uuid>
required
name
string
required
destinationUrl
string
required

As stored, which is as it was sent except that the names of any known placeholders (see CreateCampaignRequest.destinationUrl) have been lowercased. Placeholders are never substituted here: what each one becomes depends on the placement, and this is the campaign.

adCopy
string
required
platform
enum<string>
required
Available options:
TELEGRAM
distributionType
enum<string>
required
Available options:
RECOMMENDED,
MANUAL
mediaAssets
object[]
required
budget
string
required
Pattern: ^-?\d+(\.\d{1,6})?$
Example:

"125.500000"

startsAt
string<date>
required
endsAt
string<date>
required
dailyDistribution
object[]
required
approvalMode
enum<string>
required
Available options:
OPERATOR,
USER
creativeChangesAllowed
boolean
required
status
enum<string>
required
Available options:
ACTIVE,
COMPLETED,
ARCHIVED
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
objective
enum<string> | null
Available options:
AWARENESS,
TRAFFIC,
CONVERSIONS,
APP_INSTALLS