Ads

Run approved submissions as ads on the brand's own ad accounts, and see what each creator's work drives.

Campaigns

A campaign runs on one Meta, TikTok, Google, or Snapchat connection. Its creatives are approved submissions; creators earn what their program pays.

JSON

{
  "name": "Spring launch – Meta",
  "connection": "conn_02PEZI7pHWLT3UpakbRmfNB",
  "destination": { "type": "website", "value": "https://acme.com/spring" },
  "budget": { "daily": 5000 },
  "audience": { "countries": ["US"], "ageMin": 21 },
  "creatives": ["sub_14XA4WGiSOmaVI3B4QLm4Fs"],
  "ad": { "primaryText": "Made for spring.", "callToAction": "shop_now" }
}

It's created on the ad platform paused; set status to live to start it, or send "launch": false to save it as ready without creating it. Pause, resume, or archive with status. A webhook reports when publishing finishes.

Ad defaults

PATCH /v1/ad-defaults sets what new campaigns start with: objective, Meta Advantage+ audience, naming, and tracking.

Tracking

tracking sets click tracking: urlParameters on every platform, a Google trackingUrlTemplate, and TikTok click and impression trackers. Change it on a live campaign with PATCH.

Ad sets and ads

GET /v1/ad-sets and GET /v1/ads list what's running. PATCH renames, pauses, or archives them; Meta and TikTok ad sets also take bidding and audience, including saved audiences and interests (GET /v1/ad-audiences, GET /v1/ad-interests). Copy any of them with POST …/copies.

Get daily ad results, or creators' organic results, optionally filtered and split by campaign, submission, creator or platform; as a creator, your own work's ad results across brands

SDKlucra.analytics.retrieve({ query })

Query parameters

fromstringrequired
tostringrequired
modeenum
paid: ad results. organic: creators' own posts' views and engagement, for the last 90 days at most.
paidorganic
campaigncamp_…
submissionsub_…
programprog_…
creatorcrtr_…
platformenum
metatiktokgooglesnapchatinstagram
groupstring
Split each day by campaign, submission (the creative), creator and/or platform, e.g. group=campaign,submission.

POST/v1/campaigns

write

Create and launch a campaign

SDKlucra.campaigns.create({ body })

Body

namestringrequired
objectiveenum
Defaults to the account's (GET /v1/ad-defaults), conversions unless set.
conversionstrafficawareness
destinationobjectrequired
Show 2 child fieldsHide child fields
- typestringrequired
- valuestring
budgetobjectrequired
billingLimitinteger
Stop spending once the campaign has spent this much, in cents.
scheduleobjectrequired
Show 2 child fieldsHide child fields
- startDatestringrequired
- endDatestring
audienceobject
Show 5 child fieldsHide child fields
- countriesstring[]
- ageMininteger
- ageMaxinteger
- genderenum
  allfemalemale
- expandboolean
  Meta: let it reach people beyond this audience when it expects better results (Advantage+ audience).
creativessub_…[]required
adSetsobject[]
How the creatives are split into ad sets; by default one ad per creative, packed into as few ad sets as the platform allows.
Show 4 child fieldsHide child fields
- idadset_…
  An `adset_` ID from the campaign's `adSets`, to keep that ad set across edits; omit to add one.
- namestring
- budgetSharenumber
  Its share of the campaign budget, in percent; shares add up to 100.
- adsobject[]required
  Show 3 child fieldsHide child fields
  idad_…
  An `ad_` ID from the ad set's `ads`, to keep it.
  creativesub_…required
  namestring
adobjectrequired
Show 3 child fieldsHide child fields
- primaryTextstringrequired
- callToActionstringrequired
- headlinestring
optimizationEventstring
settingsobject
Show 9 child fieldsHide child fields
- pixelstring
  Meta, TikTok or Snapchat pixel ID in that platform's own format.
- conversionstring
  Meta custom conversion ID, or Google conversion action resource name.
- conversionGoalstring
  Google custom conversion goal resource name.
- revenueConversionstring
  Google conversion action that reports revenue, for revenue-share campaigns.
- appstring
  Meta or TikTok registered app ID, for app store destinations.
- logostring
  Google: square logo asset resource name and business name, for website destinations.
- businessNamestring
- targetCpainteger
  Google app campaigns: target cost per action in cents.
- locationsstring[]
  TikTok location IDs.
trackingobject
Show 4 child fieldsHide child fields
- urlParametersstring
  Added to every click's landing page: Meta's URL parameters, Google's final URL suffix, appended to TikTok's landing page.
- trackingUrlTemplatestring
  Google: the tracking template clicks go through.
- clickTrackingUrlstring
  TikTok: your measurement partner's click tracker.
- impressionTrackingUrlstring
  TikTok: your measurement partner's impression tracker.
connectionconn_…required
identityenum
Run ads under the brand's identity (default) or the creator's.
brandcreator
launchboolean
Create it on the ad platform now, paused until you PATCH status "live" (the default), or false to save it ready to create later.

Response20127 fieldsShow

idcamp_…
namestring
statusenum
draftreadylivepausedneeds_attentionarchived
objectivestring
connectionconn_…nullable
platformstringnullable
destinationobject
Show 2 child fieldsHide child fields
- typestring
- valuestringnullable
budgetobject
In cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
scheduleobject
Show 2 child fieldsHide child fields
- startDatestring
- endDatestringnullable
audienceobject
Show 5 child fieldsHide child fields
- countriesstring[]
- ageMinnumbernullable
- ageMaxnumbernullable
- genderstringnullable
- expandboolean
adobject
Show 3 child fieldsHide child fields
- primaryTextstringnullable
- callToActionstringnullable
- headlinestringnullable
optimizationEventstringnullable
settingsany
trackingany
identityenum
brandcreator
creativessub_…[]
adSetsobject[]
The campaign's ad sets as planned: each one's share of the budget and its ads. Names can use {{variables}}.
Show 4 child fieldsHide child fields
- idadset_…
- namestring
- budgetSharenumber
  In percent.
- adsobject[]
  Show 3 child fieldsHide child fields
  idad_…
  creativesub_…
  namestring
billingLimitnumbernullable
The campaign stops spending at this amount, in cents.
creatorPayobject
What creators earn, as their programs' pay set it when the campaign was saved.
Show 6 child fieldsHide child fields
- modelenum
  ad_spendattributed_revenuelead
- creatorSharenumbernullable
  The creator's share of spend or revenue, in percent.
- feenumbernullable
  The total usage fee on spend or revenue, in percent.
- leadAmountintegernullable
  What a creator earns per lead, in cents.
- capintegernullable
  The most a creator earns from the campaign, in cents.
- revenueEventstringnullable
platformsobject[]
How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
- platformstring
- statusstring
- errorstringnullable
pendingChangeobjectnullable
A change still settling: waiting for the brand's approval (PATCH `pendingChange: "approved"`), or running on the ad platforms.
Show 2 child fieldsHide child fields
- actionstring
- statusenum
  awaiting_approvalin_progress
partnerApprovalobjectnullable
Show 4 child fieldsHide child fields
- statusstring
- notestringnullable
- requestedAtstringnullable
- reviewedAtstringnullable
createdByPartneracct_…nullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

POST/v1/campaigns/:id/copies

write

Copy a campaign with its ad sets and ads, as a new campaign

SDKlucra.campaigns.copies.create({ path: { id }, body })

Path parameters

idstringrequired

Body

namestring
Defaults to the source's name with " (copy)".
launchboolean
Publish the copy now, or (default) save it ready to launch with PATCH status "live".

Response20127 fieldsShow

idcamp_…
namestring
statusenum
draftreadylivepausedneeds_attentionarchived
objectivestring
connectionconn_…nullable
platformstringnullable
destinationobject
Show 2 child fieldsHide child fields
- typestring
- valuestringnullable
budgetobject
In cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
scheduleobject
Show 2 child fieldsHide child fields
- startDatestring
- endDatestringnullable
audienceobject
Show 5 child fieldsHide child fields
- countriesstring[]
- ageMinnumbernullable
- ageMaxnumbernullable
- genderstringnullable
- expandboolean
adobject
Show 3 child fieldsHide child fields
- primaryTextstringnullable
- callToActionstringnullable
- headlinestringnullable
optimizationEventstringnullable
settingsany
trackingany
identityenum
brandcreator
creativessub_…[]
adSetsobject[]
The campaign's ad sets as planned: each one's share of the budget and its ads. Names can use {{variables}}.
Show 4 child fieldsHide child fields
- idadset_…
- namestring
- budgetSharenumber
  In percent.
- adsobject[]
  Show 3 child fieldsHide child fields
  idad_…
  creativesub_…
  namestring
billingLimitnumbernullable
The campaign stops spending at this amount, in cents.
creatorPayobject
What creators earn, as their programs' pay set it when the campaign was saved.
Show 6 child fieldsHide child fields
- modelenum
  ad_spendattributed_revenuelead
- creatorSharenumbernullable
  The creator's share of spend or revenue, in percent.
- feenumbernullable
  The total usage fee on spend or revenue, in percent.
- leadAmountintegernullable
  What a creator earns per lead, in cents.
- capintegernullable
  The most a creator earns from the campaign, in cents.
- revenueEventstringnullable
platformsobject[]
How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
- platformstring
- statusstring
- errorstringnullable
pendingChangeobjectnullable
A change still settling: waiting for the brand's approval (PATCH `pendingChange: "approved"`), or running on the ad platforms.
Show 2 child fieldsHide child fields
- actionstring
- statusenum
  awaiting_approvalin_progress
partnerApprovalobjectnullable
Show 4 child fieldsHide child fields
- statusstring
- notestringnullable
- requestedAtstringnullable
- reviewedAtstringnullable
createdByPartneracct_…nullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/campaigns

read

List campaigns

SDKlucra.campaigns.list({ query })

Query parameters

limitinteger
cursorstring
createdAfterstring
Only items created at or after this time.
createdBeforestring
Only items created before this time.
statusenum
draftreadylivepausedneeds_attentionarchived
platformenum
metatiktokgooglesnapchat
connectionconn_…

Response200A page of items, 27 fields each, and nextCursorShow

idcamp_…
namestring
statusenum
draftreadylivepausedneeds_attentionarchived
objectivestring
connectionconn_…nullable
platformstringnullable
destinationobject
Show 2 child fieldsHide child fields
- typestring
- valuestringnullable
budgetobject
In cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
scheduleobject
Show 2 child fieldsHide child fields
- startDatestring
- endDatestringnullable
audienceobject
Show 5 child fieldsHide child fields
- countriesstring[]
- ageMinnumbernullable
- ageMaxnumbernullable
- genderstringnullable
- expandboolean
adobject
Show 3 child fieldsHide child fields
- primaryTextstringnullable
- callToActionstringnullable
- headlinestringnullable
optimizationEventstringnullable
settingsany
trackingany
identityenum
brandcreator
creativessub_…[]
adSetsobject[]
The campaign's ad sets as planned: each one's share of the budget and its ads. Names can use {{variables}}.
Show 4 child fieldsHide child fields
- idadset_…
- namestring
- budgetSharenumber
  In percent.
- adsobject[]
  Show 3 child fieldsHide child fields
  idad_…
  creativesub_…
  namestring
billingLimitnumbernullable
The campaign stops spending at this amount, in cents.
creatorPayobject
What creators earn, as their programs' pay set it when the campaign was saved.
Show 6 child fieldsHide child fields
- modelenum
  ad_spendattributed_revenuelead
- creatorSharenumbernullable
  The creator's share of spend or revenue, in percent.
- feenumbernullable
  The total usage fee on spend or revenue, in percent.
- leadAmountintegernullable
  What a creator earns per lead, in cents.
- capintegernullable
  The most a creator earns from the campaign, in cents.
- revenueEventstringnullable
platformsobject[]
How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
- platformstring
- statusstring
- errorstringnullable
pendingChangeobjectnullable
A change still settling: waiting for the brand's approval (PATCH `pendingChange: "approved"`), or running on the ad platforms.
Show 2 child fieldsHide child fields
- actionstring
- statusenum
  awaiting_approvalin_progress
partnerApprovalobjectnullable
Show 4 child fieldsHide child fields
- statusstring
- notestringnullable
- requestedAtstringnullable
- reviewedAtstringnullable
createdByPartneracct_…nullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/campaigns/:id

read

Get a campaign

SDKlucra.campaigns.retrieve({ path: { id } })

Path parameters

idstringrequired

Response20027 fieldsShow

idcamp_…
namestring
statusenum
draftreadylivepausedneeds_attentionarchived
objectivestring
connectionconn_…nullable
platformstringnullable
destinationobject
Show 2 child fieldsHide child fields
- typestring
- valuestringnullable
budgetobject
In cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
scheduleobject
Show 2 child fieldsHide child fields
- startDatestring
- endDatestringnullable
audienceobject
Show 5 child fieldsHide child fields
- countriesstring[]
- ageMinnumbernullable
- ageMaxnumbernullable
- genderstringnullable
- expandboolean
adobject
Show 3 child fieldsHide child fields
- primaryTextstringnullable
- callToActionstringnullable
- headlinestringnullable
optimizationEventstringnullable
settingsany
trackingany
identityenum
brandcreator
creativessub_…[]
adSetsobject[]
The campaign's ad sets as planned: each one's share of the budget and its ads. Names can use {{variables}}.
Show 4 child fieldsHide child fields
- idadset_…
- namestring
- budgetSharenumber
  In percent.
- adsobject[]
  Show 3 child fieldsHide child fields
  idad_…
  creativesub_…
  namestring
billingLimitnumbernullable
The campaign stops spending at this amount, in cents.
creatorPayobject
What creators earn, as their programs' pay set it when the campaign was saved.
Show 6 child fieldsHide child fields
- modelenum
  ad_spendattributed_revenuelead
- creatorSharenumbernullable
  The creator's share of spend or revenue, in percent.
- feenumbernullable
  The total usage fee on spend or revenue, in percent.
- leadAmountintegernullable
  What a creator earns per lead, in cents.
- capintegernullable
  The most a creator earns from the campaign, in cents.
- revenueEventstringnullable
platformsobject[]
How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
- platformstring
- statusstring
- errorstringnullable
pendingChangeobjectnullable
A change still settling: waiting for the brand's approval (PATCH `pendingChange: "approved"`), or running on the ad platforms.
Show 2 child fieldsHide child fields
- actionstring
- statusenum
  awaiting_approvalin_progress
partnerApprovalobjectnullable
Show 4 child fieldsHide child fields
- statusstring
- notestringnullable
- requestedAtstringnullable
- reviewedAtstringnullable
createdByPartneracct_…nullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

PATCH/v1/campaigns/:id

write

Change a campaign, its ad sets' budgets, or its status: launch, pause, resume, retry or archive

SDKlucra.campaigns.update({ path: { id }, body })

Path parameters

idstringrequired

Body

namestring
objectiveenum
conversions (default) optimizes for `optimizationEvent`; traffic (link clicks) and awareness (reach) run on Meta websites (beta).
conversionstrafficawareness
destinationobject
Show 2 child fieldsHide child fields
- typestringrequired
- valuestring
budgetobject
billingLimitinteger
Stop spending once the campaign has spent this much, in cents.
scheduleobject
Show 2 child fieldsHide child fields
- startDatestringrequired
- endDatestring
audienceobject
Show 5 child fieldsHide child fields
- countriesstring[]
- ageMininteger
- ageMaxinteger
- genderenum
  allfemalemale
- expandboolean
  Meta: let it reach people beyond this audience when it expects better results (Advantage+ audience).
creativessub_…[]
adSetsobject[]
How the creatives are split into ad sets; by default one ad per creative, packed into as few ad sets as the platform allows.
Show 4 child fieldsHide child fields
- idadset_…
  An `adset_` ID from the campaign's `adSets`, to keep that ad set across edits; omit to add one.
- namestring
- budgetSharenumber
  Its share of the campaign budget, in percent; shares add up to 100.
- adsobject[]required
  Show 3 child fieldsHide child fields
  idad_…
  An `ad_` ID from the ad set's `ads`, to keep it.
  creativesub_…required
  namestring
adobject
Show 3 child fieldsHide child fields
- primaryTextstringrequired
- callToActionstringrequired
- headlinestring
optimizationEventstring
settingsobject
Show 9 child fieldsHide child fields
- pixelstring
  Meta, TikTok or Snapchat pixel ID in that platform's own format.
- conversionstring
  Meta custom conversion ID, or Google conversion action resource name.
- conversionGoalstring
  Google custom conversion goal resource name.
- revenueConversionstring
  Google conversion action that reports revenue, for revenue-share campaigns.
- appstring
  Meta or TikTok registered app ID, for app store destinations.
- logostring
  Google: square logo asset resource name and business name, for website destinations.
- businessNamestring
- targetCpainteger
  Google app campaigns: target cost per action in cents.
- locationsstring[]
  TikTok location IDs.
trackingobject
Show 4 child fieldsHide child fields
- urlParametersstring
  Added to every click's landing page: Meta's URL parameters, Google's final URL suffix, appended to TikTok's landing page.
- trackingUrlTemplatestring
  Google: the tracking template clicks go through.
- clickTrackingUrlstring
  TikTok: your measurement partner's click tracker.
- impressionTrackingUrlstring
  TikTok: your measurement partner's impression tracker.
statusenum
live publishes a ready campaign, resumes a paused one, or retries a launch that needs attention.
pausedlivearchived
adSetBudgetsobject[]
New budgets, in cents, for launched Meta or Snapchat ad sets, by their IDs from the campaign's `adSets` (GET /v1/campaigns/:id).
Show 2 child fieldsHide child fields
- idadset_…required
- budgetintegerrequired
pendingChangestring
As the brand: approves the change a partner made, which `pendingChange` shows awaiting approval.
approved
versioninteger

Response20027 fieldsShow

idcamp_…
namestring
statusenum
draftreadylivepausedneeds_attentionarchived
objectivestring
connectionconn_…nullable
platformstringnullable
destinationobject
Show 2 child fieldsHide child fields
- typestring
- valuestringnullable
budgetobject
In cents.
currencystring
Lowercase ISO 4217 code, e.g. usd.
scheduleobject
Show 2 child fieldsHide child fields
- startDatestring
- endDatestringnullable
audienceobject
Show 5 child fieldsHide child fields
- countriesstring[]
- ageMinnumbernullable
- ageMaxnumbernullable
- genderstringnullable
- expandboolean
adobject
Show 3 child fieldsHide child fields
- primaryTextstringnullable
- callToActionstringnullable
- headlinestringnullable
optimizationEventstringnullable
settingsany
trackingany
identityenum
brandcreator
creativessub_…[]
adSetsobject[]
The campaign's ad sets as planned: each one's share of the budget and its ads. Names can use {{variables}}.
Show 4 child fieldsHide child fields
- idadset_…
- namestring
- budgetSharenumber
  In percent.
- adsobject[]
  Show 3 child fieldsHide child fields
  idad_…
  creativesub_…
  namestring
billingLimitnumbernullable
The campaign stops spending at this amount, in cents.
creatorPayobject
What creators earn, as their programs' pay set it when the campaign was saved.
Show 6 child fieldsHide child fields
- modelenum
  ad_spendattributed_revenuelead
- creatorSharenumbernullable
  The creator's share of spend or revenue, in percent.
- feenumbernullable
  The total usage fee on spend or revenue, in percent.
- leadAmountintegernullable
  What a creator earns per lead, in cents.
- capintegernullable
  The most a creator earns from the campaign, in cents.
- revenueEventstringnullable
platformsobject[]
How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
- platformstring
- statusstring
- errorstringnullable
pendingChangeobjectnullable
A change still settling: waiting for the brand's approval (PATCH `pendingChange: "approved"`), or running on the ad platforms.
Show 2 child fieldsHide child fields
- actionstring
- statusenum
  awaiting_approvalin_progress
partnerApprovalobjectnullable
Show 4 child fieldsHide child fields
- statusstring
- notestringnullable
- requestedAtstringnullable
- reviewedAtstringnullable
createdByPartneracct_…nullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/ad-fields

read

List the settings each ad platform takes for campaigns, ad sets and ads

SDKlucra.adFields.list({ query })

Query parameters

limitinteger
cursorstring
createdAfterstring
Only items created at or after this time.
createdBeforestring
Only items created before this time.
platformenum
Also returns the universal settings unless `universal`.
metatiktokgooglesnapchatuniversal
resourceenum
campaignad_setadcreative
statusenum
implementedplannedprovider_gatedread_onlydeprecated

GET/v1/ad-defaults

read

Get what the account's new campaigns start with

SDKlucra.adDefaults.retrieve()

PATCH/v1/ad-defaults

write

Change what the account's new campaigns start with

SDKlucra.adDefaults.update({ body })

Body

objectiveenumnullable
conversionstrafficawareness
audienceExpansionbooleannullable
namingobject
Show 2 child fieldsHide child fields
- adSetstringnullable
- adstringnullable
trackingobjectnullable
Show 4 child fieldsHide child fields
- urlParametersstring
  Added to every click's landing page: Meta's URL parameters, Google's final URL suffix, appended to TikTok's landing page.
- trackingUrlTemplatestring
  Google: the tracking template clicks go through.
- clickTrackingUrlstring
  TikTok: your measurement partner's click tracker.
- impressionTrackingUrlstring
  TikTok: your measurement partner's impression tracker.

GET/v1/ad-audiences

read

List an ad account's saved audiences (Meta custom and lookalike audiences, TikTok audiences)

SDKlucra.adAudiences.list({ query })

Query parameters

limitinteger
cursorstring
createdAfterstring
Only items created at or after this time.
createdBeforestring
Only items created before this time.
connectionconn_…required
A Meta or TikTok ad account `conn_` from GET /v1/connections.

GET/v1/ad-interests

read

Search the interests an ad set can target on Meta or TikTok

SDKlucra.adInterests.list({ query })

Query parameters

limitinteger
cursorstring
createdAfterstring
Only items created at or after this time.
createdBeforestring
Only items created before this time.
connectionconn_…required
A Meta or TikTok ad account `conn_` from GET /v1/connections.
qstringrequired
What to search for, e.g. running.

GET/v1/ad-sets

read

List ad sets (Meta ad sets, TikTok and Google ad groups, Snapchat ad squads)

SDKlucra.adSets.list({ query })

Query parameters

limitinteger
cursorstring
createdAfterstring
Only items created at or after this time.
createdBeforestring
Only items created before this time.
campaigncamp_…
platformenum
metatiktokgooglesnapchat
statusenum
draftactivepausedarchiveddeletedunknown

GET/v1/ad-sets/:id

read

Get an ad set

SDKlucra.adSets.retrieve({ path: { id } })

Path parameters

idstringrequired

PATCH/v1/ad-sets/:id

write

Rename, pause, resume, archive or re-budget an ad set on its platform

SDKlucra.adSets.update({ path: { id }, body })

Path parameters

idstringrequired

Body

namestring
statusenum
active resumes it, paused pauses it, archived stops and archives it.
activepausedarchived
budgetobject
In cents. Meta ad sets only: TikTok and Google budgets live on the campaign.
biddingany
Meta and TikTok ad sets (beta).
audienceany
Meta and TikTok ad sets (beta).

POST/v1/ad-sets/:id/copies

write

Copy an ad set (and run it paused) in its campaign or another one

SDKlucra.adSets.copies.create({ path: { id }, body })

Path parameters

idstringrequired

Body

namestring
Defaults to the source's name with " (copy)".
intocamp_…
Another launched campaign on the same ad account; defaults to the source's own.

Response2021 fieldsShow

idstring
The copy's ID; it reads back from GET once the platform confirms it.

GET/v1/ads

read

List ads

SDKlucra.ads.list({ query })

Query parameters

limitinteger
cursorstring
createdAfterstring
Only items created at or after this time.
createdBeforestring
Only items created before this time.
campaigncamp_…
platformenum
metatiktokgooglesnapchat
statusenum
draftactivepausedarchiveddeletedunknown
adSetadset_…

GET/v1/ads/:id

read

Get an ad

SDKlucra.ads.retrieve({ path: { id } })

Path parameters

idstringrequired

PATCH/v1/ads/:id

write

Rename, pause, resume or archive an ad on its platform

SDKlucra.ads.update({ path: { id }, body })

Path parameters

idstringrequired

Body

namestring
statusenum
active resumes it, paused pauses it, archived stops and archives it.
activepausedarchived

POST/v1/ads/:id/copies

write

Copy an ad (and run it paused) in its ad set or another one

SDKlucra.ads.copies.create({ path: { id }, body })

Path parameters

idstringrequired

Body

namestring
Defaults to the source's name with " (copy)".
intoadset_…
Another launched ad set on the same ad account; defaults to the source's own.

Response2021 fieldsShow

idstring
The copy's ID; it reads back from GET once the platform confirms it.

GET/v1/ad-authorizations

As creatorread

List ad authorizations: a brand's requests, or, as a creator, the ones asked of you

SDKlucra.adAuthorizations.list({ query })

Query parameters

limitinteger
cursorstring
createdAfterstring
Only items created at or after this time.
createdBeforestring
Only items created before this time.
submissionsub_…
platformenum
tiktokmeta
statusstring
One or more, comma-separated: requested, granted, revoked, expired.

Response200A page of items, 14 fields each, and nextCursorShow

idadauth_…
submissionsub_…
creatorcrtr_…
accountacct_…
The brand that asks.
brandNamestring
platformenum
tiktokmeta
statusenum
requested by the brand, granted by the creator, revoked by either; expired once `expiresAt` passes.
requestedgrantedrevokedexpired
codestringnullable
The TikTok Spark code the creator granted with; null for Meta and until granted.
authorizedAtstringnullable
expiresAtstringnullable
revokedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/ad-authorizations/:id

As creatorread

Get an ad authorization

SDKlucra.adAuthorizations.retrieve({ path: { id } })

Path parameters

idstringrequired

Response20014 fieldsShow

idadauth_…
submissionsub_…
creatorcrtr_…
accountacct_…
The brand that asks.
brandNamestring
platformenum
tiktokmeta
statusenum
requested by the brand, granted by the creator, revoked by either; expired once `expiresAt` passes.
requestedgrantedrevokedexpired
codestringnullable
The TikTok Spark code the creator granted with; null for Meta and until granted.
authorizedAtstringnullable
expiresAtstringnullable
revokedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

POST/v1/ad-authorizations

write

Ask a submission's creator to authorize it as a TikTok Spark or Meta partnership ad

SDKlucra.adAuthorizations.create({ body })

Body

submissionsub_…required
An approved submission of a creator.
platformenumrequired
tiktokmeta

Response20114 fieldsShow

idadauth_…
submissionsub_…
creatorcrtr_…
accountacct_…
The brand that asks.
brandNamestring
platformenum
tiktokmeta
statusenum
requested by the brand, granted by the creator, revoked by either; expired once `expiresAt` passes.
requestedgrantedrevokedexpired
codestringnullable
The TikTok Spark code the creator granted with; null for Meta and until granted.
authorizedAtstringnullable
expiresAtstringnullable
revokedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

PATCH/v1/ad-authorizations/:id

As creatorwrite

Grant an ad authorization as its creator, or revoke it

SDKlucra.adAuthorizations.update({ path: { id }, body })

Path parameters

idstringrequired

Body

statusenumrequired
grantedrevoked
codestring
With granted on TikTok: the Spark code the creator generated for the post.
expiresAtstring
With granted: when the creator's authorization ends, as they set it on the platform.
versioninteger

Response20014 fieldsShow

idadauth_…
submissionsub_…
creatorcrtr_…
accountacct_…
The brand that asks.
brandNamestring
platformenum
tiktokmeta
statusenum
requested by the brand, granted by the creator, revoked by either; expired once `expiresAt` passes.
requestedgrantedrevokedexpired
codestringnullable
The TikTok Spark code the creator granted with; null for Meta and until granted.
authorizedAtstringnullable
expiresAtstringnullable
revokedAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

Campaigns

Ad defaults

Tracking

Ad sets and ads

Ad fields

Ad authorizations

Analytics

Endpoints

Query parameters

Body

Path parameters

Body

Query parameters

Path parameters

Path parameters

Body

Query parameters

Body

Query parameters

Query parameters

Query parameters

Path parameters

Path parameters

Body

Path parameters

Body

Query parameters

Path parameters

Path parameters

Body

Path parameters

Body

Query parameters

Path parameters

Body

Path parameters

Body