Sign in

Reference

Build on the Lucra API.

Get API keyQuickstart

Drag a sticker to move it, or use the arrow keys while focused.

Ads

Campaigns, ad sets, ads and daily results.

Run approved submissions as ads on the brand's own ad accounts, and see what each creator's work drives. Connect an ad account first with a connection.

Create a campaign

A campaign runs on one Meta, TikTok, Google or Snapchat connection. Its creatives are approved submissions, and their creators earn what their program pays. This one spends $50 a day:

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

Lucra sets the campaign up on the ad platform right away; it's processing until that's done. By default it then turns on. Send "launch": false to leave it paused, or scheduledLaunchAt to turn it on later.

Change its status to live, paused or archived with PATCH /v1/campaigns/:id. Webhooks report when publishing finishes (campaign.published) or needs attention.

How creators are credited

When creators earn a share of revenue or a fixed amount per lead, attribution sets what counts. lucra counts your Lucra Pixel's matches of one conversion from each ad's link; platform counts what the ad platform reports. New campaigns default to lucra when your pixel is verified and the destination is a website:

JSON
{ "attribution": { "source": "lucra", "conversion": "conv_1fK7pQ2wXy9LmN4bVc8RtZa" } }

Leave out conversion to use an active purchase (revenue share) or lead (per lead) conversion; Lucra creates one if you have none. It can't change once the campaign is on its ad platform. Ad-spend pay always counts the platform's spend.

Ad defaults

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

Tracking

tracking sets click tracking on a campaign: urlParameters on every platform, a Google trackingUrlTemplate, and TikTok click and impression trackers. You can change it on a live campaign.

Every ad's link also carries lucra_id (its video) and lucra_campaign (the campaign), which the Lucra Pixel reads; Lucra sets them, replacing any already in the URL.

Boost an existing TikTok post

Run a post that's already on TikTok as a Spark Ad, with no upload. Add it to the brand's library with POST /v1/submissions, by the creator's Spark code, the post's full link, or both:

JSON
{ "post": { "connection": "conn_02PEZI7pHWLT3UpakbRmfNB", "sparkCode": "#Abc123…" } }

With a code, the post is ready at once: its existingPost.ready is true and existingPost.authorizedUntil says when the code ends. Then put its sub_ ID in a TikTok campaign's creatives, on the same connection. A campaign runs either existing posts or uploaded videos, and existing posts run only on TikTok.

With just a link, Lucra asks the creator for a code. The submission's adAuthorization is the request (platform: "tiktok"). Read it with GET /v1/ad-authorizations/:id for its requestUrl: send that link to the creator, who pastes their code there, with no Lucra account needed. A creator who connected that TikTok account to Lucra also gets the request in the app. When the code arrives, you get ad_authorization.granted and the post is ready. If the creator sends you the code instead, send it with POST /v1/submissions again, or PATCH /v1/ad-authorizations/:id with { "status": "granted", "sparkCode": "…" }.

Three days before a code ends, Lucra asks the creator for a new one and sends ad_authorization.requested. An existing post never pays its creator through Lucra: it isn't part of a program.

Ad sets and ads

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

Ad fields

GET /v1/ad-fields lists every setting each platform takes, with the platform's own name and docs.

Run as the creator

To run a submission as a Meta Partnership Ad under the creator's own account, request an authorization with POST /v1/ad-authorizations. The creator grants it, and you get ad_authorization.granted. On TikTok, a campaign with identity: "creator" runs under the creator's whole account, which they approve once to your Business Center; until they have, the campaign save answers 422 saying what's missing.

Ads Lucra didn't launch

Lucra also reads back the other ads in each connected ad account: the last 90 days on the first 30-minute sync after the account connects, then on every sync like Lucra's own. List them with GET /v1/ads?source=external: each has source: "external", its platform ID, and its campaign and ad set on the platform (platformCampaign, platformAdSet). They're read-only, and they're never billed, settled or paid out. Their status is unknown: Lucra reports their results, not their state.

Analytics

GET /v1/analytics returns daily spend, revenue, clicks, conversions and paidViews between from and to. Paid views are each platform's own video view count: Meta's 3-second views, TikTok's video plays, Snapchat's 2-second views and Google's TrueView views. Split each day with group, by campaign, submission, creator, ad or platform. source=external reads the ads Lucra didn't launch instead, and source=all both:

TypeScript
const { data } = await lucra.analytics.retrieve({
  query: { from: "2026-10-01", to: "2026-10-07", group: "creator" },
})

Endpoints

GET/v1/analytics
As creatorread

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

const { data } = await lucra.analytics.retrieve({
  query: { from: "…", to: "…" },
})

Query parameters

  • fromstring· required
  • tostring· required
  • 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
  • sourceenum

    Paid results of: lucra, the ads Lucra launched (the default); external, the other ads in your connected ad accounts (no campaign, submission or creator, and no usage fees); or all of them.

    lucraexternalall
  • groupstring

    Split each day by campaign, submission (the creative), creator, ad and/or platform, e.g. group=campaign,submission.

POST/v1/campaigns
write

Create and launch a campaign

const { data } = await lucra.campaigns.create({
  body: { name: "…", destination: {}, budget: {} },
})

Body

  • namestring· required
  • objectiveenum

    Defaults to the account's (GET /v1/ad-defaults), conversions unless set.

    conversionstrafficawareness
  • destinationobject· required
    Show 2 child fields
    • typestring· required
    • valuestring
  • budgetobject· required
  • billingLimitinteger

    Stop spending once the campaign has spent this much, in cents.

  • scheduleobject· required
    Show 2 child fields
    • startDatestring· required
    • endDatestring
  • scheduledLaunchAtstringnullable

    Turn the campaign on by itself at this time; null cancels. Until then it stays paused, and a create with a future time doesn't launch now.

  • audienceobject
    Show 5 child fields
    • countriesenum[]
      USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAE
    • 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 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 fields
      • idad_…

        An ad_ ID from the ad set's ads, to keep it.

      • creativesub_…· required
      • namestring
  • adobject· required
    Show 3 child fields
    • primaryTextstring· required
    • callToActionenum· required
      book_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribe
    • headlinestring
  • optimizationEventenum
    installpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontact
  • settingsobject
    Show 10 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.

    • budgetOptimizationenum

      TikTok only: ad_set (the default) gives each ad set its share of the budget; campaign lets TikTok's campaign budget optimization move one campaign budget (at least $20) between ad sets, ignoring the split. Fixed once the campaign is set up on TikTok.

      ad_setcampaign
  • trackingobject
    Show 4 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 campaigns set up before Smart+ only (Smart+ ads have no trackers): your measurement partner's click tracker.

    • impressionTrackingUrlstring

      TikTok campaigns set up before Smart+ only: your measurement partner's impression tracker.

  • attributionobject

    How creators' revenue-share or per-lead pay is counted: the ad platform's reported results (platform) or your Lucra pixel's conversions from the ad's link (lucra; the default when your pixel is verified and the destination is a website). Fixed once the campaign is on its ad platform; ad-spend pay is always platform.

    Show 2 child fields
    • sourceenum· required
      platformlucra
    • conversionconv_…

      With lucra: the conv_ whose matches count (GET /v1/conversions). Defaults to an active purchase (revenue pay) or lead (per-lead pay) conversion, created if you have none.

  • connectionconn_…· required
  • identityenum

    Run ads under the brand's identity (default) or the creator's.

    brandcreator
  • launchboolean

    Every new campaign is set up on its ad platform right away, paused (status processing until done). launch (the default) also turns it on; false, or a future scheduledLaunchAt, leaves it paused.

Response20129 fieldsShow
  • idcamp_…
  • namestring
  • statusenum

    processing while it's set up or changed on the ad platform; in_review while the platform reviews its ads; then live or paused as the platform reports.

    draftprocessingin_reviewlivepausedneeds_attentionarchived
  • objectiveenum
    conversionsawarenesstrafficengagementleadsapp_promotionsales
  • connectionconn_…nullable
  • platformstringnullable
  • destinationobject
    Show 2 child fields
    • typeenum
      websitemobile_appios_app_storegoogle_playdeep_link
    • valuestringnullable
  • budgetobject

    In cents.

  • currencystring

    Lowercase ISO 4217 code, e.g. usd.

  • scheduleobject
    Show 2 child fields
    • startDatestring
    • endDatestringnullable
  • scheduledLaunchAtstringnullable
  • audienceobject
    Show 5 child fields
    • countriesenum[]
      USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAE
    • ageMinnumbernullable
    • ageMaxnumbernullable
    • genderenumnullable
      allfemalemale
    • expandboolean
  • adobject
    Show 3 child fields
    • primaryTextstringnullable
    • callToActionenumnullable
      book_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribe
    • headlinestringnullable
  • optimizationEventenumnullable
    installpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontact
  • 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 fields
    • idadset_…
    • namestring
    • budgetSharenumber

      In percent.

    • adsobject[]
      Show 3 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 5 child fields
    • modelenum
      ad_spendattributed_revenuelead
    • creatorSharenumbernullable

      The creator's share of 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
  • attributionobject

    How creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of conversion (lucra).

    Show 2 child fields
    • sourceenum
      platformlucra
    • conversionconv_…nullable
  • platformsobject[]

    How each ad platform reports the campaign.

    Show 3 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 fields
    • actionstring
    • statusenum
      awaiting_approvalin_progress
  • partnerApprovalobjectnullable
    Show 4 child fields
    • statusenum
      draftpendingapprovedrejectedchanges_requested
    • 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

const { data } = await lucra.campaigns.copies.create({
  path: { id: "camp_…" },
  body: { name: "…" },
})

Path parameters

  • idcamp_…· required

Body

  • namestring

    Defaults to the source's name with " (copy)".

  • launchboolean

    Turn the copy on once it's set up, or (default) leave it paused on the platform, to launch with PATCH status "live".

Response20129 fieldsShow
  • idcamp_…
  • namestring
  • statusenum

    processing while it's set up or changed on the ad platform; in_review while the platform reviews its ads; then live or paused as the platform reports.

    draftprocessingin_reviewlivepausedneeds_attentionarchived
  • objectiveenum
    conversionsawarenesstrafficengagementleadsapp_promotionsales
  • connectionconn_…nullable
  • platformstringnullable
  • destinationobject
    Show 2 child fields
    • typeenum
      websitemobile_appios_app_storegoogle_playdeep_link
    • valuestringnullable
  • budgetobject

    In cents.

  • currencystring

    Lowercase ISO 4217 code, e.g. usd.

  • scheduleobject
    Show 2 child fields
    • startDatestring
    • endDatestringnullable
  • scheduledLaunchAtstringnullable
  • audienceobject
    Show 5 child fields
    • countriesenum[]
      USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAE
    • ageMinnumbernullable
    • ageMaxnumbernullable
    • genderenumnullable
      allfemalemale
    • expandboolean
  • adobject
    Show 3 child fields
    • primaryTextstringnullable
    • callToActionenumnullable
      book_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribe
    • headlinestringnullable
  • optimizationEventenumnullable
    installpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontact
  • 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 fields
    • idadset_…
    • namestring
    • budgetSharenumber

      In percent.

    • adsobject[]
      Show 3 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 5 child fields
    • modelenum
      ad_spendattributed_revenuelead
    • creatorSharenumbernullable

      The creator's share of 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
  • attributionobject

    How creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of conversion (lucra).

    Show 2 child fields
    • sourceenum
      platformlucra
    • conversionconv_…nullable
  • platformsobject[]

    How each ad platform reports the campaign.

    Show 3 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 fields
    • actionstring
    • statusenum
      awaiting_approvalin_progress
  • partnerApprovalobjectnullable
    Show 4 child fields
    • statusenum
      draftpendingapprovedrejectedchanges_requested
    • 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

const { data } = await lucra.campaigns.list({
  query: { status: "draft" },
})

Query parameters

  • statusenum
    draftlivepausedneeds_attentionarchived
  • platformenum
    metatiktokgooglesnapchat
  • connectionconn_…

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 29 fields each, and nextCursorShow
  • idcamp_…
  • namestring
  • statusenum

    processing while it's set up or changed on the ad platform; in_review while the platform reviews its ads; then live or paused as the platform reports.

    draftprocessingin_reviewlivepausedneeds_attentionarchived
  • objectiveenum
    conversionsawarenesstrafficengagementleadsapp_promotionsales
  • connectionconn_…nullable
  • platformstringnullable
  • destinationobject
    Show 2 child fields
    • typeenum
      websitemobile_appios_app_storegoogle_playdeep_link
    • valuestringnullable
  • budgetobject

    In cents.

  • currencystring

    Lowercase ISO 4217 code, e.g. usd.

  • scheduleobject
    Show 2 child fields
    • startDatestring
    • endDatestringnullable
  • scheduledLaunchAtstringnullable
  • audienceobject
    Show 5 child fields
    • countriesenum[]
      USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAE
    • ageMinnumbernullable
    • ageMaxnumbernullable
    • genderenumnullable
      allfemalemale
    • expandboolean
  • adobject
    Show 3 child fields
    • primaryTextstringnullable
    • callToActionenumnullable
      book_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribe
    • headlinestringnullable
  • optimizationEventenumnullable
    installpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontact
  • 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 fields
    • idadset_…
    • namestring
    • budgetSharenumber

      In percent.

    • adsobject[]
      Show 3 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 5 child fields
    • modelenum
      ad_spendattributed_revenuelead
    • creatorSharenumbernullable

      The creator's share of 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
  • attributionobject

    How creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of conversion (lucra).

    Show 2 child fields
    • sourceenum
      platformlucra
    • conversionconv_…nullable
  • platformsobject[]

    How each ad platform reports the campaign.

    Show 3 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 fields
    • actionstring
    • statusenum
      awaiting_approvalin_progress
  • partnerApprovalobjectnullable
    Show 4 child fields
    • statusenum
      draftpendingapprovedrejectedchanges_requested
    • 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

const { data } = await lucra.campaigns.retrieve({
  path: { id: "camp_…" },
})

Path parameters

  • idcamp_…· required
Response20029 fieldsShow
  • idcamp_…
  • namestring
  • statusenum

    processing while it's set up or changed on the ad platform; in_review while the platform reviews its ads; then live or paused as the platform reports.

    draftprocessingin_reviewlivepausedneeds_attentionarchived
  • objectiveenum
    conversionsawarenesstrafficengagementleadsapp_promotionsales
  • connectionconn_…nullable
  • platformstringnullable
  • destinationobject
    Show 2 child fields
    • typeenum
      websitemobile_appios_app_storegoogle_playdeep_link
    • valuestringnullable
  • budgetobject

    In cents.

  • currencystring

    Lowercase ISO 4217 code, e.g. usd.

  • scheduleobject
    Show 2 child fields
    • startDatestring
    • endDatestringnullable
  • scheduledLaunchAtstringnullable
  • audienceobject
    Show 5 child fields
    • countriesenum[]
      USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAE
    • ageMinnumbernullable
    • ageMaxnumbernullable
    • genderenumnullable
      allfemalemale
    • expandboolean
  • adobject
    Show 3 child fields
    • primaryTextstringnullable
    • callToActionenumnullable
      book_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribe
    • headlinestringnullable
  • optimizationEventenumnullable
    installpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontact
  • 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 fields
    • idadset_…
    • namestring
    • budgetSharenumber

      In percent.

    • adsobject[]
      Show 3 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 5 child fields
    • modelenum
      ad_spendattributed_revenuelead
    • creatorSharenumbernullable

      The creator's share of 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
  • attributionobject

    How creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of conversion (lucra).

    Show 2 child fields
    • sourceenum
      platformlucra
    • conversionconv_…nullable
  • platformsobject[]

    How each ad platform reports the campaign.

    Show 3 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 fields
    • actionstring
    • statusenum
      awaiting_approvalin_progress
  • partnerApprovalobjectnullable
    Show 4 child fields
    • statusenum
      draftpendingapprovedrejectedchanges_requested
    • 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

const { data } = await lucra.campaigns.update({
  path: { id: "camp_…" },
  body: { name: "…" },
})

Path parameters

  • idcamp_…· required

Body

  • namestring
  • objectiveenum

    conversions (default) optimizes for optimizationEvent; traffic (link clicks) and awareness (reach) run on Meta websites (beta).

    conversionstrafficawareness
  • destinationobject
    Show 2 child fields
    • typestring· required
    • valuestring
  • budgetobject
  • billingLimitinteger

    Stop spending once the campaign has spent this much, in cents.

  • scheduleobject
    Show 2 child fields
    • startDatestring· required
    • endDatestring
  • scheduledLaunchAtstringnullable

    Turn the campaign on by itself at this time; null cancels. Until then it stays paused, and a create with a future time doesn't launch now.

  • audienceobject
    Show 5 child fields
    • countriesenum[]
      USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAE
    • 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 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 fields
      • idad_…

        An ad_ ID from the ad set's ads, to keep it.

      • creativesub_…· required
      • namestring
  • adobject
    Show 3 child fields
    • primaryTextstring· required
    • callToActionenum· required
      book_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribe
    • headlinestring
  • optimizationEventenum
    installpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontact
  • settingsobject
    Show 10 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.

    • budgetOptimizationenum

      TikTok only: ad_set (the default) gives each ad set its share of the budget; campaign lets TikTok's campaign budget optimization move one campaign budget (at least $20) between ad sets, ignoring the split. Fixed once the campaign is set up on TikTok.

      ad_setcampaign
  • trackingobject
    Show 4 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 campaigns set up before Smart+ only (Smart+ ads have no trackers): your measurement partner's click tracker.

    • impressionTrackingUrlstring

      TikTok campaigns set up before Smart+ only: your measurement partner's impression tracker.

  • attributionobject

    How creators' revenue-share or per-lead pay is counted: the ad platform's reported results (platform) or your Lucra pixel's conversions from the ad's link (lucra; the default when your pixel is verified and the destination is a website). Fixed once the campaign is on its ad platform; ad-spend pay is always platform.

    Show 2 child fields
    • sourceenum· required
      platformlucra
    • conversionconv_…

      With lucra: the conv_ whose matches count (GET /v1/conversions). Defaults to an active purchase (revenue pay) or lead (per-lead pay) conversion, created if you have none.

  • statusenum

    live turns a paused campaign on, creating it on its ad platform first if it never was; on a launch that needs attention it retries.

    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 fields
    • idadset_…· required
    • budgetinteger· required
  • pendingChangestring

    As the brand: approves the change a partner made, which pendingChange shows awaiting approval.

    approved
  • versioninteger
Response20029 fieldsShow
  • idcamp_…
  • namestring
  • statusenum

    processing while it's set up or changed on the ad platform; in_review while the platform reviews its ads; then live or paused as the platform reports.

    draftprocessingin_reviewlivepausedneeds_attentionarchived
  • objectiveenum
    conversionsawarenesstrafficengagementleadsapp_promotionsales
  • connectionconn_…nullable
  • platformstringnullable
  • destinationobject
    Show 2 child fields
    • typeenum
      websitemobile_appios_app_storegoogle_playdeep_link
    • valuestringnullable
  • budgetobject

    In cents.

  • currencystring

    Lowercase ISO 4217 code, e.g. usd.

  • scheduleobject
    Show 2 child fields
    • startDatestring
    • endDatestringnullable
  • scheduledLaunchAtstringnullable
  • audienceobject
    Show 5 child fields
    • countriesenum[]
      USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAE
    • ageMinnumbernullable
    • ageMaxnumbernullable
    • genderenumnullable
      allfemalemale
    • expandboolean
  • adobject
    Show 3 child fields
    • primaryTextstringnullable
    • callToActionenumnullable
      book_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribe
    • headlinestringnullable
  • optimizationEventenumnullable
    installpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontact
  • 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 fields
    • idadset_…
    • namestring
    • budgetSharenumber

      In percent.

    • adsobject[]
      Show 3 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 5 child fields
    • modelenum
      ad_spendattributed_revenuelead
    • creatorSharenumbernullable

      The creator's share of 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
  • attributionobject

    How creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of conversion (lucra).

    Show 2 child fields
    • sourceenum
      platformlucra
    • conversionconv_…nullable
  • platformsobject[]

    How each ad platform reports the campaign.

    Show 3 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 fields
    • actionstring
    • statusenum
      awaiting_approvalin_progress
  • partnerApprovalobjectnullable
    Show 4 child fields
    • statusenum
      draftpendingapprovedrejectedchanges_requested
    • 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

const { data } = await lucra.adFields.list({
  query: { platform: "meta" },
})

Query parameters

  • platformenum

    Also returns the universal settings unless universal.

    metatiktokgooglesnapchatuniversal
  • resourceenum
    campaignad_setadcreative
  • statusenum
    implementedplannedprovider_gatedread_onlydeprecated

Plus paging: limit, cursor, createdAfter and createdBefore.

GET/v1/ad-defaults
read

Get what the account's new campaigns start with

const { data } = await lucra.adDefaults.retrieve()
PATCH/v1/ad-defaults
write

Change what the account's new campaigns start with

const { data } = await lucra.adDefaults.update({
  body: { objective: "conversions" },
})

Body

  • objectiveenumnullable
    conversionstrafficawareness
  • audienceExpansionbooleannullable
  • namingobject
    Show 2 child fields
    • adSetstringnullable
    • adstringnullable
  • trackingobjectnullable
    Show 4 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 campaigns set up before Smart+ only (Smart+ ads have no trackers): your measurement partner's click tracker.

    • impressionTrackingUrlstring

      TikTok campaigns set up before Smart+ only: 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)

const { data } = await lucra.adAudiences.list({
  query: { connection: "conn_…" },
})

Query parameters

  • connectionconn_…· required

    A Meta or TikTok ad account conn_ from GET /v1/connections.

Plus paging: limit, cursor, createdAfter and createdBefore.

GET/v1/ad-interests
read

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

const { data } = await lucra.adInterests.list({
  query: { connection: "conn_…", q: "…" },
})

Query parameters

  • connectionconn_…· required

    A Meta or TikTok ad account conn_ from GET /v1/connections.

  • qstring· required

    What to search for, e.g. running.

Plus paging: limit, cursor, createdAfter and createdBefore.

GET/v1/ad-sets
read

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

const { data } = await lucra.adSets.list({
  query: { campaign: "camp_…" },
})

Query parameters

  • campaigncamp_…
  • platformenum
    metatiktokgooglesnapchat
  • statusenum
    draftactivepausedarchiveddeletedunknown

Plus paging: limit, cursor, createdAfter and createdBefore.

GET/v1/ad-sets/:id
read

Get an ad set

const { data } = await lucra.adSets.retrieve({
  path: { id: "…" },
})

Path parameters

  • idstring· required
PATCH/v1/ad-sets/:id
write

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

const { data } = await lucra.adSets.update({
  path: { id: "…" },
  body: { name: "…" },
})

Path parameters

  • idstring· required

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

const { data } = await lucra.adSets.copies.create({
  path: { id: "…" },
  body: { name: "…" },
})

Path parameters

  • idstring· required

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: the ones Lucra launched, or with source=external the other ads in your connected ad accounts

const { data } = await lucra.ads.list({
  query: { campaign: "camp_…" },
})

Query parameters

  • campaigncamp_…
  • platformenum
    metatiktokgooglesnapchat
  • statusenum
    draftactivepausedarchiveddeletedunknown
  • adSetadset_…
  • sourceenum

    lucra: ads Lucra campaigns launched (the default). external: the other ads in your connected ad accounts, read back for reporting (the last 90 days on connecting, then kept current).

    lucraexternal

Plus paging: limit, cursor, createdAfter and createdBefore.

GET/v1/ads/:id
read

Get an ad

const { data } = await lucra.ads.retrieve({
  path: { id: "…" },
})

Path parameters

  • idstring· required
PATCH/v1/ads/:id
write

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

const { data } = await lucra.ads.update({
  path: { id: "…" },
  body: { name: "…" },
})

Path parameters

  • idstring· required

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

const { data } = await lucra.ads.copies.create({
  path: { id: "…" },
  body: { name: "…" },
})

Path parameters

  • idstring· required

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

const { data } = await lucra.adAuthorizations.list({
  query: { submission: "sub_…" },
})

Query parameters

  • submissionsub_…
  • platformenum
    metatiktok
  • statusstring

    One or more, comma-separated: requested, granted, revoked, expired.

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 16 fields each, and nextCursorShow
  • idadauth_…
  • submissionsub_…
  • creatorcrtr_…nullable
  • accountacct_…

    The brand that asks.

  • brandNamestring
  • platformenum
    metatiktok
  • statusenum

    requested by the brand, granted by the creator, revoked by either; expired once expiresAt passes.

    requestedgrantedrevokedexpired
  • handlestringnullable

    On TikTok, the handle of the post's creator.

  • postobjectnullable

    On TikTok, the post the brand wants to run.

    Show 4 child fields
    • urlstringnullable
    • handlestringnullable
    • captionstringnullable
    • thumbnailUrlstringnullable

      TikTok's poster image; it expires, so read the authorization again for a fresh one.

  • requestUrlstringnullable

    On TikTok, a link the creator opens, without a Lucra account, to send their Spark code.

  • authorizedAtstringnullable
  • expiresAtstringnullable

    When the creator's authorization (on TikTok, their Spark code) ends.

  • 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

const { data } = await lucra.adAuthorizations.retrieve({
  path: { id: "adauth_…" },
})

Path parameters

  • idadauth_…· required
Response20016 fieldsShow
  • idadauth_…
  • submissionsub_…
  • creatorcrtr_…nullable
  • accountacct_…

    The brand that asks.

  • brandNamestring
  • platformenum
    metatiktok
  • statusenum

    requested by the brand, granted by the creator, revoked by either; expired once expiresAt passes.

    requestedgrantedrevokedexpired
  • handlestringnullable

    On TikTok, the handle of the post's creator.

  • postobjectnullable

    On TikTok, the post the brand wants to run.

    Show 4 child fields
    • urlstringnullable
    • handlestringnullable
    • captionstringnullable
    • thumbnailUrlstringnullable

      TikTok's poster image; it expires, so read the authorization again for a fresh one.

  • requestUrlstringnullable

    On TikTok, a link the creator opens, without a Lucra account, to send their Spark code.

  • authorizedAtstringnullable
  • expiresAtstringnullable

    When the creator's authorization (on TikTok, their Spark code) ends.

  • 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 Meta partnership ad, or an existing TikTok post's creator for a Spark code

const { data } = await lucra.adAuthorizations.create({
  body: { submission: "sub_…", platform: "meta" },
})

Body

  • submissionsub_…· required

    An approved submission of a creator, or on TikTok an existing post in your library.

  • platformenum· required
    metatiktok
Response20116 fieldsShow
  • idadauth_…
  • submissionsub_…
  • creatorcrtr_…nullable
  • accountacct_…

    The brand that asks.

  • brandNamestring
  • platformenum
    metatiktok
  • statusenum

    requested by the brand, granted by the creator, revoked by either; expired once expiresAt passes.

    requestedgrantedrevokedexpired
  • handlestringnullable

    On TikTok, the handle of the post's creator.

  • postobjectnullable

    On TikTok, the post the brand wants to run.

    Show 4 child fields
    • urlstringnullable
    • handlestringnullable
    • captionstringnullable
    • thumbnailUrlstringnullable

      TikTok's poster image; it expires, so read the authorization again for a fresh one.

  • requestUrlstringnullable

    On TikTok, a link the creator opens, without a Lucra account, to send their Spark code.

  • authorizedAtstringnullable
  • expiresAtstringnullable

    When the creator's authorization (on TikTok, their Spark code) ends.

  • 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 (on TikTok, with the post's Spark code), or revoke it

const { data } = await lucra.adAuthorizations.update({
  path: { id: "adauth_…" },
  body: { status: "granted" },
})

Path parameters

  • idadauth_…· required

Body

  • statusenum· required
    grantedrevoked
  • sparkCodestring

    On TikTok, with granted: the Spark code the creator made for the post. The brand may send one the creator gave them too. A new code renews an expired authorization.

  • expiresAtstring

    On Meta, with granted: when the creator's authorization ends, as they set it on the platform.

  • versioninteger
Response20016 fieldsShow
  • idadauth_…
  • submissionsub_…
  • creatorcrtr_…nullable
  • accountacct_…

    The brand that asks.

  • brandNamestring
  • platformenum
    metatiktok
  • statusenum

    requested by the brand, granted by the creator, revoked by either; expired once expiresAt passes.

    requestedgrantedrevokedexpired
  • handlestringnullable

    On TikTok, the handle of the post's creator.

  • postobjectnullable

    On TikTok, the post the brand wants to run.

    Show 4 child fields
    • urlstringnullable
    • handlestringnullable
    • captionstringnullable
    • thumbnailUrlstringnullable

      TikTok's poster image; it expires, so read the authorization again for a fresh one.

  • requestUrlstringnullable

    On TikTok, a link the creator opens, without a Lucra account, to send their Spark code.

  • authorizedAtstringnullable
  • expiresAtstringnullable

    When the creator's authorization (on TikTok, their Spark code) ends.

  • revokedAtstringnullable
  • versioninteger

    Send it back on PATCH to reject edits based on a stale read.

  • createdAtstring
  • updatedAtstring