Every endpoint with what it accepts and returns, generated from the API itself so it always matches. Each shows its SDK method. Conventions are in the introduction.
Account
/v1/accountGet the key's own account
const { data } = await lucra.account.retrieve()Response20021 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account
partner.brandFee).Show 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
partnerobjectnullableA partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
creatorTakeRateobjectnullableShow 1 child fieldHide child fields
percentnumber
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
emailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe account's logo, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
paymentMethodobjectnullableA brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
statusstringactivebrandstringnullablelast4stringnullable
payoutsobjectWhere it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
brandsobjectnullableThe brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
creatorsobjectnullableThe account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
descriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
listingobjectnullableA partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
listedbooleanheadlinestringnullablecategoriesstring[]registeredAtstringnullable
versionintegercreatedAtstringupdatedAtstring
/v1/accountUpdate the key's own account
const { data } = await lucra.account.update({
body: { creatorTakeRate: {} },
})Body
creatorTakeRateobjectnullableThe partner's cut of each payment to a creator it brought, taken from the creator's side. Up to 20%.
Show 1 child fieldHide child fields
percentnumber· required
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenum· requiredad_spendgmvpercentnumber· required
profilePicturefile_…nullablenamestringdescriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
typeenumbrandpartnerlistingobjectShow 3 child fieldsHide child fields
listedbooleanheadlinestringnullablecategoriesstring[]
versioninteger
Response20021 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account
partner.brandFee).Show 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
partnerobjectnullableA partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
creatorTakeRateobjectnullableShow 1 child fieldHide child fields
percentnumber
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
emailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe account's logo, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
paymentMethodobjectnullableA brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
statusstringactivebrandstringnullablelast4stringnullable
payoutsobjectWhere it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
brandsobjectnullableThe brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
creatorsobjectnullableThe account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
descriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
listingobjectnullableA partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
listedbooleanheadlinestringnullablecategoriesstring[]registeredAtstringnullable
versionintegercreatedAtstringupdatedAtstring
Analytics
/v1/analyticsGet 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· requiredtostring· requiredmodeenumpaid: ad results. organic: creators' own posts' views and engagement, for the last 90 days at most.
paidorganiccampaigncamp_…submissionsub_…programprog_…creatorcrtr_…platformenummetatiktokgooglesnapchatinstagramsourceenumPaid 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.
lucraexternalallgroupstringSplit each day by campaign, submission (the creative), creator, ad and/or platform, e.g. group=campaign,submission.
Applications
/v1/applicationsList applications
const { data } = await lucra.applications.list({
query: { program: "prog_…" },
})Query parameters
programprog_…creatorcrtr_…statusstringOne or more, comma-separated: pending, approved, rejected, withdrawn.
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 15 fields each, and nextCursorShow
idappl_…programprog_…creatorcrtr_…statusenumpendingapprovedrejectedwithdrawnremovedbooleanRejected after being approved: the brand took the creator out of the program.
payobjectnullablePay the brand set for this creator over the program's (PATCH
pay); null when the program's pay applies.acceptedAtis set by the creator's next action in the program.Show 2 child fieldsHide child fields
overrideobjectShow 3 child fieldsHide child fields
rulesobject[]capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobject
acceptedAtstringnullable
payVersionintegernullableThe program pay version this creator is paid on; null until admitted. Below the program's
payVersionuntil their next action in the program accepts the newer pay.payStatusenumpast_due once a charge for this creator's program pay failed its last retry; back to current when a retry succeeds on an updated payment method.
currentpast_dueagreementsRequiredbooleanThe brand invited the creator, who still has to accept the program's agreements; the application is approved once they do.
reviewedAtstringnullableagreementsany[]On GET /v1/applications/:id as the creator while
agreementsRequired: what joining accepts.partnerFeeobjectnullableWith
agreements: the share of the creator's pay their partner takes, if any.Show 2 child fieldsHide child fields
partnerstringpercentnumber
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/applications/:idGet an application
const { data } = await lucra.applications.retrieve({
path: { id: "appl_…" },
})Path parameters
idappl_…· required
Response20015 fieldsShow
idappl_…programprog_…creatorcrtr_…statusenumpendingapprovedrejectedwithdrawnremovedbooleanRejected after being approved: the brand took the creator out of the program.
payobjectnullablePay the brand set for this creator over the program's (PATCH
pay); null when the program's pay applies.acceptedAtis set by the creator's next action in the program.Show 2 child fieldsHide child fields
overrideobjectShow 3 child fieldsHide child fields
rulesobject[]capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobject
acceptedAtstringnullable
payVersionintegernullableThe program pay version this creator is paid on; null until admitted. Below the program's
payVersionuntil their next action in the program accepts the newer pay.payStatusenumpast_due once a charge for this creator's program pay failed its last retry; back to current when a retry succeeds on an updated payment method.
currentpast_dueagreementsRequiredbooleanThe brand invited the creator, who still has to accept the program's agreements; the application is approved once they do.
reviewedAtstringnullableagreementsany[]On GET /v1/applications/:id as the creator while
agreementsRequired: what joining accepts.partnerFeeobjectnullableWith
agreements: the share of the creator's pay their partner takes, if any.Show 2 child fieldsHide child fields
partnerstringpercentnumber
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/applicationsInvite a creator to a program, or apply as one
const { data } = await lucra.applications.create({
body: { program: "prog_…" },
})Body
programprog_…· requiredcreatorcrtr_…
Response20115 fieldsShow
idappl_…programprog_…creatorcrtr_…statusenumpendingapprovedrejectedwithdrawnremovedbooleanRejected after being approved: the brand took the creator out of the program.
payobjectnullablePay the brand set for this creator over the program's (PATCH
pay); null when the program's pay applies.acceptedAtis set by the creator's next action in the program.Show 2 child fieldsHide child fields
overrideobjectShow 3 child fieldsHide child fields
rulesobject[]capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobject
acceptedAtstringnullable
payVersionintegernullableThe program pay version this creator is paid on; null until admitted. Below the program's
payVersionuntil their next action in the program accepts the newer pay.payStatusenumpast_due once a charge for this creator's program pay failed its last retry; back to current when a retry succeeds on an updated payment method.
currentpast_dueagreementsRequiredbooleanThe brand invited the creator, who still has to accept the program's agreements; the application is approved once they do.
reviewedAtstringnullableagreementsany[]On GET /v1/applications/:id as the creator while
agreementsRequired: what joining accepts.partnerFeeobjectnullableWith
agreements: the share of the creator's pay their partner takes, if any.Show 2 child fieldsHide child fields
partnerstringpercentnumber
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/applications/:idApprove, reject or reopen an application, or set the creator's pay; as the creator, withdraw it or accept an invitation (approved)
const { data } = await lucra.applications.update({
path: { id: "appl_…" },
body: { status: "pending" },
})Path parameters
idappl_…· required
Body
statusenumpending reopens a decided application for review; a creator withdraws their own with withdrawn, or joins a program they're invited to with approved, accepting its agreements.
pendingapprovedrejectedwithdrawnpayobjectnullableMerged over the program's pay for this creator; null returns them to the program's pay.
Show 3 child fieldsHide child fields
rulesobject[]capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobject
versioninteger
Response20015 fieldsShow
idappl_…programprog_…creatorcrtr_…statusenumpendingapprovedrejectedwithdrawnremovedbooleanRejected after being approved: the brand took the creator out of the program.
payobjectnullablePay the brand set for this creator over the program's (PATCH
pay); null when the program's pay applies.acceptedAtis set by the creator's next action in the program.Show 2 child fieldsHide child fields
overrideobjectShow 3 child fieldsHide child fields
rulesobject[]capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobject
acceptedAtstringnullable
payVersionintegernullableThe program pay version this creator is paid on; null until admitted. Below the program's
payVersionuntil their next action in the program accepts the newer pay.payStatusenumpast_due once a charge for this creator's program pay failed its last retry; back to current when a retry succeeds on an updated payment method.
currentpast_dueagreementsRequiredbooleanThe brand invited the creator, who still has to accept the program's agreements; the application is approved once they do.
reviewedAtstringnullableagreementsany[]On GET /v1/applications/:id as the creator while
agreementsRequired: what joining accepts.partnerFeeobjectnullableWith
agreements: the share of the creator's pay their partner takes, if any.Show 2 child fieldsHide child fields
partnerstringpercentnumber
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Balance
/v1/balanceGet the balance: the account's commissions, or a creator's earnings
const { data } = await lucra.balance.retrieve()Response2003 fieldsShow
balancesobject[]Show 9 child fieldsHide child fields
currencystringLowercase ISO 4217 code, e.g. usd.
availableintegerA creator's earnings ready to send to their Stripe balance, sent within minutes once their identity is verified; 0 for an account.
pendingintegerA creator's earnings waiting on the brand's payment; 0 for an account.
heldintegerA creator's earnings held while a dispute is reviewed; 0 for an account.
paidintegerA creator's earnings sent to their Stripe balance, all time; 0 for an account.
spentintegerDeprecated: always 0.
refundableintegerDeprecated: always 0.
withdrawableintegerIn this balance's Stripe account (a creator's, or an account's commissions), ready to withdraw with POST /v1/withdrawals.
instantWithdrawableintegerHow much of
withdrawablecan go out instantly, to a debit card.
depositMethodsenum[]Deprecated: always empty.
bankcardwithdrawalFeesobjectWhat a withdrawal costs; it comes out of the amount.
Show 2 child fieldsHide child fields
instantobjectShow 2 child fieldsHide child fields
percentnumberA percent, e.g. 1.5 for 1.5%.
minimumintegerThe least an instant withdrawal costs.
crossBorderobjectAdded outside the US; 0 in the US.
Show 1 child fieldHide child fields
percentnumberA percent, e.g. 1.5 for 1.5%.
/v1/balance/taxGet US tax reporting: whether a taxpayer ID is on file, and what Lucra paid each year
const { data } = await lucra.balance.tax.retrieve()Response2005 fieldsShow
taxIdenumThe SSN or EIN on the Stripe account: verified by Stripe, provided, flagged (failed) or missing.
missingprovidedverifiedfailedrequiredbooleanTrue when withdrawals wait for a taxpayer ID (US, paid at least
thresholdthis year): add it with POST /v1/connections (provider stripe).thresholdintegerWhat Lucra can pay a US payee in a calendar year before a taxpayer ID is needed, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
yearsobject[]Newest first.
Show 2 child fieldsHide child fields
yearintegerreportableintegerWhat Lucra paid this balance that year (UTC), in cents: transfers less fees taken back.
/v1/balance/transactionsList every ledger line on the account
const { data } = await lucra.balance.transactions.list({
query: { type: "…" },
})Query parameters
typestringComma-separated transaction types, e.g. creator_earning,platform_fee.
programprog_…
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 15 fields each, and nextCursorShow
idtxn_…typestringstatusstringamountintegerSigned, in cents: positive adds to the balance.
feeintegerIn cents.
netintegerSigned, in cents:
amountlessfee.balancenumbernullablecurrencystringLowercase ISO 4217 code, e.g. usd.
descriptionstringnullableWhat it is, e.g. Creator payment.
memostringnullablesourcestringcounterpartyobjectShow 3 child fieldsHide child fields
typeenumpartnerpayment_methodcreatorplatformaccountidcrtr_…nullableSet when the other side is a creator.
namestringnullable
campaigncamp_…nullableprogramprog_…nullableoccurredAtstring
Brands
/v1/brandsList the brands this key reaches, and a partner's brands whose relationship ended
const { data } = await lucra.brands.list({
query: { status: "active" },
})Response200A page of items, 21 fields each, and nextCursorShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account
partner.brandFee).Show 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
partnerobjectnullableA partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
creatorTakeRateobjectnullableShow 1 child fieldHide child fields
percentnumber
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
emailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe account's logo, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
paymentMethodobjectnullableA brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
statusstringactivebrandstringnullablelast4stringnullable
payoutsobjectWhere it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
brandsobjectnullableThe brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
creatorsobjectnullableThe account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
descriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
listingobjectnullableA partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
listedbooleanheadlinestringnullablecategoriesstring[]registeredAtstringnullable
versionintegercreatedAtstringupdatedAtstring
/v1/brands/:idGet a brand
const { data } = await lucra.brands.retrieve({
path: { id: "acct_…" },
})Path parameters
idacct_…· required
Response20021 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account
partner.brandFee).Show 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
partnerobjectnullableA partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
creatorTakeRateobjectnullableShow 1 child fieldHide child fields
percentnumber
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
emailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe account's logo, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
paymentMethodobjectnullableA brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
statusstringactivebrandstringnullablelast4stringnullable
payoutsobjectWhere it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
brandsobjectnullableThe brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
creatorsobjectnullableThe account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
descriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
listingobjectnullableA partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
listedbooleanheadlinestringnullablecategoriesstring[]registeredAtstringnullable
versionintegercreatedAtstringupdatedAtstring
/v1/brandsCreate a brand a partner manages
const { data } = await lucra.brands.create({
body: { name: "…" },
})Body
namestring· requiredbrandFeeobjectShow 2 child fieldsHide child fields
ofenum· requiredad_spendgmvpercentnumber· required
emailstringphonestring
Response20121 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account
partner.brandFee).Show 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
partnerobjectnullableA partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
creatorTakeRateobjectnullableShow 1 child fieldHide child fields
percentnumber
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
emailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe account's logo, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
paymentMethodobjectnullableA brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
statusstringactivebrandstringnullablelast4stringnullable
payoutsobjectWhere it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
brandsobjectnullableThe brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
creatorsobjectnullableThe account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
descriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
listingobjectnullableA partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
listedbooleanheadlinestringnullablecategoriesstring[]registeredAtstringnullable
versionintegercreatedAtstringupdatedAtstring
/v1/brands/:idUpdate a brand a partner manages
const { data } = await lucra.brands.update({
path: { id: "acct_…" },
body: { brandFee: {} },
})Path parameters
idacct_…· required
Body
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenum· requiredad_spendgmvpercentnumber· required
profilePicturefile_…nullablenamestringdescriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
versioninteger
Response20021 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's own fee on this brand; null when it's on the partner's default (GET /v1/account
partner.brandFee).Show 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
partnerobjectnullableA partner's take rates; null for a brand.
Show 2 child fieldsHide child fields
creatorTakeRateobjectnullableShow 1 child fieldHide child fields
percentnumber
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenumad_spendgmvpercentnumber
emailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe account's logo, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
paymentMethodobjectnullableA brand's payment method; null means none yet (add one with POST /v1/connections, provider card), and always null for a partner.
Show 3 child fieldsHide child fields
statusstringactivebrandstringnullablelast4stringnullable
payoutsobjectWhere it's paid: verified identity lets earnings reach its balance; a bank account is asked for on the first withdrawal. Set up with POST /v1/connections (provider stripe).
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
brandsobjectnullableThe brands a partner key reaches; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
creatorsobjectnullableThe account's creators and roster; null on a managed brand.
Show 1 child fieldHide child fields
countinteger
descriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
listingobjectnullableA partner's marketplace listing; null for a brand.
Show 4 child fieldsHide child fields
listedbooleanheadlinestringnullablecategoriesstring[]registeredAtstringnullable
versionintegercreatedAtstringupdatedAtstring
Campaigns
/v1/campaignsCreate and launch a campaign
const { data } = await lucra.campaigns.create({
body: { name: "…", destination: {}, budget: {} },
})Body
namestring· requiredobjectiveenumDefaults to the account's (GET /v1/ad-defaults), conversions unless set.
conversionstrafficawarenessdestinationobject· requiredShow 2 child fieldsHide child fields
typestring· requiredvaluestring
budgetobject· requiredbillingLimitintegerStop spending once the campaign has spent this much, in cents.
scheduleobject· requiredShow 2 child fieldsHide child fields
startDatestring· requiredendDatestring
scheduledLaunchAtstringnullableTurn 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.
audienceobjectShow 5 child fieldsHide child fields
countriesenum[]USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAEageMinintegerageMaxintegergenderenumallfemalemaleexpandbooleanMeta: let it reach people beyond this audience when it expects better results (Advantage+ audience).
creativessub_…[]· requiredadSetsobject[]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'sadSets, to keep that ad set across edits; omit to add one.namestringbudgetSharenumberIts share of the campaign budget, in percent; shares add up to 100.
adsobject[]· requiredShow 3 child fieldsHide child fields
idad_…An
ad_ID from the ad set'sads, to keep it.creativesub_…· requirednamestring
adobject· requiredShow 3 child fieldsHide child fields
primaryTextstring· requiredcallToActionenum· requiredbook_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribeheadlinestring
optimizationEventenuminstallpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontactsettingsobjectShow 10 child fieldsHide child fields
pixelstringMeta, TikTok or Snapchat pixel ID in that platform's own format.
conversionstringMeta custom conversion ID, or Google conversion action resource name.
conversionGoalstringGoogle custom conversion goal resource name.
revenueConversionstringGoogle conversion action that reports revenue, for revenue-share campaigns.
appstringMeta or TikTok registered app ID, for app store destinations.
logostringGoogle: square logo asset resource name and business name, for website destinations.
businessNamestringtargetCpaintegerGoogle app campaigns: target cost per action in cents.
locationsstring[]TikTok location IDs.
budgetOptimizationenumTikTok 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
trackingobjectShow 4 child fieldsHide child fields
urlParametersstringAdded to every click's landing page: Meta's URL parameters, Google's final URL suffix, appended to TikTok's landing page.
trackingUrlTemplatestringGoogle: the tracking template clicks go through.
clickTrackingUrlstringTikTok campaigns set up before Smart+ only (Smart+ ads have no trackers): your measurement partner's click tracker.
impressionTrackingUrlstringTikTok campaigns set up before Smart+ only: your measurement partner's impression tracker.
attributionobjectHow 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 fieldsHide child fields
sourceenum· requiredplatformlucraconversionconv_…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_…· requiredidentityenumRun ads under the brand's identity (default) or the creator's.
brandcreatorlaunchbooleanEvery 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_…namestringstatusenumprocessing 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_attentionarchivedobjectiveenumconversionsawarenesstrafficengagementleadsapp_promotionsalesconnectionconn_…nullableplatformstringnullabledestinationobjectShow 2 child fieldsHide child fields
typeenumwebsitemobile_appios_app_storegoogle_playdeep_linkvaluestringnullable
budgetobjectIn cents.
currencystringLowercase ISO 4217 code, e.g. usd.
scheduleobjectShow 2 child fieldsHide child fields
startDatestringendDatestringnullable
scheduledLaunchAtstringnullableaudienceobjectShow 5 child fieldsHide child fields
countriesenum[]USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAEageMinnumbernullableageMaxnumbernullablegenderenumnullableallfemalemaleexpandboolean
adobjectShow 3 child fieldsHide child fields
primaryTextstringnullablecallToActionenumnullablebook_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribeheadlinestringnullable
optimizationEventenumnullableinstallpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontactsettingsanytrackinganyidentityenumbrandcreatorcreativessub_…[]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_…namestringbudgetSharenumberIn percent.
adsobject[]Show 3 child fieldsHide child fields
idad_…creativesub_…namestring
billingLimitnumbernullableThe campaign stops spending at this amount, in cents.
creatorPayobjectWhat creators earn, as their programs' pay set it when the campaign was saved.
Show 5 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
attributionobjectHow creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of
conversion(lucra).Show 2 child fieldsHide child fields
sourceenumplatformlucraconversionconv_…nullable
platformsobject[]How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
platformstringstatusstringerrorstringnullable
pendingChangeobjectnullableA change still settling: waiting for the brand's approval (PATCH
pendingChange: "approved"), or running on the ad platforms.Show 2 child fieldsHide child fields
actionstringstatusenumawaiting_approvalin_progress
partnerApprovalobjectnullableShow 4 child fieldsHide child fields
statusenumdraftpendingapprovedrejectedchanges_requestednotestringnullablerequestedAtstringnullablereviewedAtstringnullable
createdByPartneracct_…nullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/campaigns/:id/copiesCopy 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
namestringDefaults to the source's name with " (copy)".
launchbooleanTurn 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_…namestringstatusenumprocessing 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_attentionarchivedobjectiveenumconversionsawarenesstrafficengagementleadsapp_promotionsalesconnectionconn_…nullableplatformstringnullabledestinationobjectShow 2 child fieldsHide child fields
typeenumwebsitemobile_appios_app_storegoogle_playdeep_linkvaluestringnullable
budgetobjectIn cents.
currencystringLowercase ISO 4217 code, e.g. usd.
scheduleobjectShow 2 child fieldsHide child fields
startDatestringendDatestringnullable
scheduledLaunchAtstringnullableaudienceobjectShow 5 child fieldsHide child fields
countriesenum[]USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAEageMinnumbernullableageMaxnumbernullablegenderenumnullableallfemalemaleexpandboolean
adobjectShow 3 child fieldsHide child fields
primaryTextstringnullablecallToActionenumnullablebook_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribeheadlinestringnullable
optimizationEventenumnullableinstallpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontactsettingsanytrackinganyidentityenumbrandcreatorcreativessub_…[]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_…namestringbudgetSharenumberIn percent.
adsobject[]Show 3 child fieldsHide child fields
idad_…creativesub_…namestring
billingLimitnumbernullableThe campaign stops spending at this amount, in cents.
creatorPayobjectWhat creators earn, as their programs' pay set it when the campaign was saved.
Show 5 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
attributionobjectHow creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of
conversion(lucra).Show 2 child fieldsHide child fields
sourceenumplatformlucraconversionconv_…nullable
platformsobject[]How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
platformstringstatusstringerrorstringnullable
pendingChangeobjectnullableA change still settling: waiting for the brand's approval (PATCH
pendingChange: "approved"), or running on the ad platforms.Show 2 child fieldsHide child fields
actionstringstatusenumawaiting_approvalin_progress
partnerApprovalobjectnullableShow 4 child fieldsHide child fields
statusenumdraftpendingapprovedrejectedchanges_requestednotestringnullablerequestedAtstringnullablereviewedAtstringnullable
createdByPartneracct_…nullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/campaignsList campaigns
const { data } = await lucra.campaigns.list({
query: { status: "draft" },
})Query parameters
statusenumdraftlivepausedneeds_attentionarchivedplatformenummetatiktokgooglesnapchatconnectionconn_…
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 29 fields each, and nextCursorShow
idcamp_…namestringstatusenumprocessing 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_attentionarchivedobjectiveenumconversionsawarenesstrafficengagementleadsapp_promotionsalesconnectionconn_…nullableplatformstringnullabledestinationobjectShow 2 child fieldsHide child fields
typeenumwebsitemobile_appios_app_storegoogle_playdeep_linkvaluestringnullable
budgetobjectIn cents.
currencystringLowercase ISO 4217 code, e.g. usd.
scheduleobjectShow 2 child fieldsHide child fields
startDatestringendDatestringnullable
scheduledLaunchAtstringnullableaudienceobjectShow 5 child fieldsHide child fields
countriesenum[]USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAEageMinnumbernullableageMaxnumbernullablegenderenumnullableallfemalemaleexpandboolean
adobjectShow 3 child fieldsHide child fields
primaryTextstringnullablecallToActionenumnullablebook_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribeheadlinestringnullable
optimizationEventenumnullableinstallpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontactsettingsanytrackinganyidentityenumbrandcreatorcreativessub_…[]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_…namestringbudgetSharenumberIn percent.
adsobject[]Show 3 child fieldsHide child fields
idad_…creativesub_…namestring
billingLimitnumbernullableThe campaign stops spending at this amount, in cents.
creatorPayobjectWhat creators earn, as their programs' pay set it when the campaign was saved.
Show 5 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
attributionobjectHow creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of
conversion(lucra).Show 2 child fieldsHide child fields
sourceenumplatformlucraconversionconv_…nullable
platformsobject[]How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
platformstringstatusstringerrorstringnullable
pendingChangeobjectnullableA change still settling: waiting for the brand's approval (PATCH
pendingChange: "approved"), or running on the ad platforms.Show 2 child fieldsHide child fields
actionstringstatusenumawaiting_approvalin_progress
partnerApprovalobjectnullableShow 4 child fieldsHide child fields
statusenumdraftpendingapprovedrejectedchanges_requestednotestringnullablerequestedAtstringnullablereviewedAtstringnullable
createdByPartneracct_…nullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/campaigns/:idGet a campaign
const { data } = await lucra.campaigns.retrieve({
path: { id: "camp_…" },
})Path parameters
idcamp_…· required
Response20029 fieldsShow
idcamp_…namestringstatusenumprocessing 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_attentionarchivedobjectiveenumconversionsawarenesstrafficengagementleadsapp_promotionsalesconnectionconn_…nullableplatformstringnullabledestinationobjectShow 2 child fieldsHide child fields
typeenumwebsitemobile_appios_app_storegoogle_playdeep_linkvaluestringnullable
budgetobjectIn cents.
currencystringLowercase ISO 4217 code, e.g. usd.
scheduleobjectShow 2 child fieldsHide child fields
startDatestringendDatestringnullable
scheduledLaunchAtstringnullableaudienceobjectShow 5 child fieldsHide child fields
countriesenum[]USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAEageMinnumbernullableageMaxnumbernullablegenderenumnullableallfemalemaleexpandboolean
adobjectShow 3 child fieldsHide child fields
primaryTextstringnullablecallToActionenumnullablebook_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribeheadlinestringnullable
optimizationEventenumnullableinstallpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontactsettingsanytrackinganyidentityenumbrandcreatorcreativessub_…[]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_…namestringbudgetSharenumberIn percent.
adsobject[]Show 3 child fieldsHide child fields
idad_…creativesub_…namestring
billingLimitnumbernullableThe campaign stops spending at this amount, in cents.
creatorPayobjectWhat creators earn, as their programs' pay set it when the campaign was saved.
Show 5 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
attributionobjectHow creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of
conversion(lucra).Show 2 child fieldsHide child fields
sourceenumplatformlucraconversionconv_…nullable
platformsobject[]How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
platformstringstatusstringerrorstringnullable
pendingChangeobjectnullableA change still settling: waiting for the brand's approval (PATCH
pendingChange: "approved"), or running on the ad platforms.Show 2 child fieldsHide child fields
actionstringstatusenumawaiting_approvalin_progress
partnerApprovalobjectnullableShow 4 child fieldsHide child fields
statusenumdraftpendingapprovedrejectedchanges_requestednotestringnullablerequestedAtstringnullablereviewedAtstringnullable
createdByPartneracct_…nullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/campaigns/:idChange 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
namestringobjectiveenumconversions (default) optimizes for
optimizationEvent; traffic (link clicks) and awareness (reach) run on Meta websites (beta).conversionstrafficawarenessdestinationobjectShow 2 child fieldsHide child fields
typestring· requiredvaluestring
budgetobjectbillingLimitintegerStop spending once the campaign has spent this much, in cents.
scheduleobjectShow 2 child fieldsHide child fields
startDatestring· requiredendDatestring
scheduledLaunchAtstringnullableTurn 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.
audienceobjectShow 5 child fieldsHide child fields
countriesenum[]USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAEageMinintegerageMaxintegergenderenumallfemalemaleexpandbooleanMeta: 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'sadSets, to keep that ad set across edits; omit to add one.namestringbudgetSharenumberIts share of the campaign budget, in percent; shares add up to 100.
adsobject[]· requiredShow 3 child fieldsHide child fields
idad_…An
ad_ID from the ad set'sads, to keep it.creativesub_…· requirednamestring
adobjectShow 3 child fieldsHide child fields
primaryTextstring· requiredcallToActionenum· requiredbook_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribeheadlinestring
optimizationEventenuminstallpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontactsettingsobjectShow 10 child fieldsHide child fields
pixelstringMeta, TikTok or Snapchat pixel ID in that platform's own format.
conversionstringMeta custom conversion ID, or Google conversion action resource name.
conversionGoalstringGoogle custom conversion goal resource name.
revenueConversionstringGoogle conversion action that reports revenue, for revenue-share campaigns.
appstringMeta or TikTok registered app ID, for app store destinations.
logostringGoogle: square logo asset resource name and business name, for website destinations.
businessNamestringtargetCpaintegerGoogle app campaigns: target cost per action in cents.
locationsstring[]TikTok location IDs.
budgetOptimizationenumTikTok 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
trackingobjectShow 4 child fieldsHide child fields
urlParametersstringAdded to every click's landing page: Meta's URL parameters, Google's final URL suffix, appended to TikTok's landing page.
trackingUrlTemplatestringGoogle: the tracking template clicks go through.
clickTrackingUrlstringTikTok campaigns set up before Smart+ only (Smart+ ads have no trackers): your measurement partner's click tracker.
impressionTrackingUrlstringTikTok campaigns set up before Smart+ only: your measurement partner's impression tracker.
attributionobjectHow 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 fieldsHide child fields
sourceenum· requiredplatformlucraconversionconv_…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.
statusenumlive turns a paused campaign on, creating it on its ad platform first if it never was; on a launch that needs attention it retries.
pausedlivearchivedadSetBudgetsobject[]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_…· requiredbudgetinteger· required
pendingChangestringAs the brand: approves the change a partner made, which
pendingChangeshows awaiting approval.approvedversioninteger
Response20029 fieldsShow
idcamp_…namestringstatusenumprocessing 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_attentionarchivedobjectiveenumconversionsawarenesstrafficengagementleadsapp_promotionsalesconnectionconn_…nullableplatformstringnullabledestinationobjectShow 2 child fieldsHide child fields
typeenumwebsitemobile_appios_app_storegoogle_playdeep_linkvaluestringnullable
budgetobjectIn cents.
currencystringLowercase ISO 4217 code, e.g. usd.
scheduleobjectShow 2 child fieldsHide child fields
startDatestringendDatestringnullable
scheduledLaunchAtstringnullableaudienceobjectShow 5 child fieldsHide child fields
countriesenum[]USCAGBAUNZATBECZDKFIFRDEGRHUIEITNLNOPLPTROESSECHBRMXJPKRSGZASAAEageMinnumbernullableageMaxnumbernullablegenderenumnullableallfemalemaleexpandboolean
adobjectShow 3 child fieldsHide child fields
primaryTextstringnullablecallToActionenumnullablebook_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribeheadlinestringnullable
optimizationEventenumnullableinstallpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontactsettingsanytrackinganyidentityenumbrandcreatorcreativessub_…[]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_…namestringbudgetSharenumberIn percent.
adsobject[]Show 3 child fieldsHide child fields
idad_…creativesub_…namestring
billingLimitnumbernullableThe campaign stops spending at this amount, in cents.
creatorPayobjectWhat creators earn, as their programs' pay set it when the campaign was saved.
Show 5 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
attributionobjectHow creator pay is counted: the ad platform's results (platform) or the Lucra pixel's matches of
conversion(lucra).Show 2 child fieldsHide child fields
sourceenumplatformlucraconversionconv_…nullable
platformsobject[]How each ad platform reports the campaign.
Show 3 child fieldsHide child fields
platformstringstatusstringerrorstringnullable
pendingChangeobjectnullableA change still settling: waiting for the brand's approval (PATCH
pendingChange: "approved"), or running on the ad platforms.Show 2 child fieldsHide child fields
actionstringstatusenumawaiting_approvalin_progress
partnerApprovalobjectnullableShow 4 child fieldsHide child fields
statusenumdraftpendingapprovedrejectedchanges_requestednotestringnullablerequestedAtstringnullablereviewedAtstringnullable
createdByPartneracct_…nullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Ad fields
/v1/ad-fieldsList the settings each ad platform takes for campaigns, ad sets and ads
const { data } = await lucra.adFields.list({
query: { platform: "meta" },
})Query parameters
platformenumAlso returns the universal settings unless
universal.metatiktokgooglesnapchatuniversalresourceenumcampaignad_setadcreativestatusenumimplementedplannedprovider_gatedread_onlydeprecated
Plus paging: limit, cursor, createdAfter and createdBefore.
Ad defaults
/v1/ad-defaultsGet what the account's new campaigns start with
const { data } = await lucra.adDefaults.retrieve()/v1/ad-defaultsChange what the account's new campaigns start with
const { data } = await lucra.adDefaults.update({
body: { objective: "conversions" },
})Body
objectiveenumnullableconversionstrafficawarenessaudienceExpansionbooleannullablenamingobjectShow 2 child fieldsHide child fields
adSetstringnullableadstringnullable
trackingobjectnullableShow 4 child fieldsHide child fields
urlParametersstringAdded to every click's landing page: Meta's URL parameters, Google's final URL suffix, appended to TikTok's landing page.
trackingUrlTemplatestringGoogle: the tracking template clicks go through.
clickTrackingUrlstringTikTok campaigns set up before Smart+ only (Smart+ ads have no trackers): your measurement partner's click tracker.
impressionTrackingUrlstringTikTok campaigns set up before Smart+ only: your measurement partner's impression tracker.
Ad audiences
/v1/ad-audiencesList 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_…· requiredA Meta or TikTok ad account
conn_from GET /v1/connections.
Plus paging: limit, cursor, createdAfter and createdBefore.
Ad interests
/v1/ad-interestsSearch the interests an ad set can target on Meta or TikTok
const { data } = await lucra.adInterests.list({
query: { connection: "conn_…", q: "…" },
})Query parameters
connectionconn_…· requiredA Meta or TikTok ad account
conn_from GET /v1/connections.qstring· requiredWhat to search for, e.g. running.
Plus paging: limit, cursor, createdAfter and createdBefore.
Ad sets
/v1/ad-setsList 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_…platformenummetatiktokgooglesnapchatstatusenumdraftactivepausedarchiveddeletedunknown
Plus paging: limit, cursor, createdAfter and createdBefore.
/v1/ad-sets/:idGet an ad set
const { data } = await lucra.adSets.retrieve({
path: { id: "…" },
})Path parameters
idstring· required
/v1/ad-sets/:idRename, 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
namestringstatusenumactive resumes it, paused pauses it, archived stops and archives it.
activepausedarchivedbudgetobjectIn cents. Meta ad sets only: TikTok and Google budgets live on the campaign.
biddinganyMeta and TikTok ad sets (beta).
audienceanyMeta and TikTok ad sets (beta).
/v1/ad-sets/:id/copiesCopy 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
namestringDefaults to the source's name with " (copy)".
intocamp_…Another launched campaign on the same ad account; defaults to the source's own.
Response2021 fieldsShow
idstringThe copy's ID; it reads back from GET once the platform confirms it.
Ads
/v1/adsList 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_…platformenummetatiktokgooglesnapchatstatusenumdraftactivepausedarchiveddeletedunknownadSetadset_…sourceenumlucra: 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.
/v1/ads/:idGet an ad
const { data } = await lucra.ads.retrieve({
path: { id: "…" },
})Path parameters
idstring· required
/v1/ads/:idRename, pause, resume or archive an ad on its platform
const { data } = await lucra.ads.update({
path: { id: "…" },
body: { name: "…" },
})Path parameters
idstring· required
Body
namestringstatusenumactive resumes it, paused pauses it, archived stops and archives it.
activepausedarchived
/v1/ads/:id/copiesCopy 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
namestringDefaults 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
idstringThe copy's ID; it reads back from GET once the platform confirms it.
Connections
/v1/connections/:idGet a connection
const { data } = await lucra.connections.retrieve({
path: { id: "conn_…" },
})Path parameters
idconn_…· required
Response20012 fieldsShow
idconn_…providerenumThe platform connected.
metatiktokgooglesnapchatshopifyinstagramstatusstringThe platform connection's state, e.g. connected, active, expired; a shop is connected or reconnect_required.
namestringnullableThe ad account, the shop domain, or the creator's handle.
handlestringnullableA creator's handle on the platform; null for a brand's connections.
avatarUrlstringnullableA short-lived link to a creator account's profile photo.
lastSyncedAtstringnullableerrorstringnullableWhy a creator account's last sync failed, e.g. token_expired.
activeCampaignsintegerLive campaigns (or ones needing attention) on an ad platform connection. Campaigns only;
canDisconnectcovers every reason a disconnect is refused.canDisconnectbooleanWhether a disconnect would be accepted now: you manage the account's connections (or it's your own creator account), and no campaign, ad operation or ad plan is active on it.
createdAtstringupdatedAtstring
/v1/connections/:id/setupList an ad platform's accounts, pages and identities to pick from, and the ones picked
const { data } = await lucra.connections.setup.retrieve({
path: { id: "conn_…" },
query: { adAccountId: "…" },
})Path parameters
idconn_…· required
Query parameters
adAccountIdstringThe ad account campaigns run in (Meta, Google, Snapchat).
advertiserIdstringTikTok's advertiser account.
businessCenterIdstringTikTok's business center; send it to list the advertisers under it.
businessIdstringMeta's business; send it to list the ad accounts and pages under it.
identityIdstringThe TikTok identity ads post as.
organizationIdstringSnapchat's organization; send it to list its ad accounts.
pageIdstringThe Facebook page Meta ads post as.
profileIdstringSnapchat's public profile ads post as.
/v1/connectionsList connected ad platforms, Shopify and creator social accounts
const { data } = await lucra.connections.list()Query parameters
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 12 fields each, and nextCursorShow
idconn_…providerenumThe platform connected.
metatiktokgooglesnapchatshopifyinstagramstatusstringThe platform connection's state, e.g. connected, active, expired; a shop is connected or reconnect_required.
namestringnullableThe ad account, the shop domain, or the creator's handle.
handlestringnullableA creator's handle on the platform; null for a brand's connections.
avatarUrlstringnullableA short-lived link to a creator account's profile photo.
lastSyncedAtstringnullableerrorstringnullableWhy a creator account's last sync failed, e.g. token_expired.
activeCampaignsintegerLive campaigns (or ones needing attention) on an ad platform connection. Campaigns only;
canDisconnectcovers every reason a disconnect is refused.canDisconnectbooleanWhether a disconnect would be accepted now: you manage the account's connections (or it's your own creator account), and no campaign, ad operation or ad plan is active on it.
createdAtstringupdatedAtstring
/v1/connections/:id/syncsSync a connected shop's catalog, or, as a creator, mirror a social account's posts now
const { data } = await lucra.connections.syncs.create({
path: { id: "conn_…" },
})Path parameters
idconn_…· required
/v1/connectionsConnect a platform, payouts or a card: returns the hosted page to send the person to
const { data } = await lucra.connections.create({
body: { provider: "meta" },
})Body
providerenum· requiredA brand connects meta, google, snapchat, tiktok or shopify; a creator (
Lucra-Account: crtr_…) instagram or tiktok. stripe sets up payouts on Stripe (identity and bank until verified, then managing them), for a creator or the account itself; card adds or manages the card Lucra charges a brand.metagooglesnapchattiktokinstagramshopifystripecardshopstringWith shopify: the store's domain, like acme.myshopify.com.
countryenumWith stripe, for a creator: their payout country, required the first time. These are the countries Lucra pays out to; creators elsewhere can't be paid out yet. Stripe Global Payouts countries (paid to the bank every Monday) are accepted only while Lucra has them switched on, and never for an account's own payouts: anything else is a 422. GET /v1/payouts/countries lists the ones open now.
ATBEBGCAHRCYCZDKEEFIFRDEGRHUISIEITLVLILTLUMTNLNOPLPTROSKSIESSECHGBUSAUINIDILJPJMMXMCMANZSMSGTTreturnUrlstringWhere the person comes back to, with
status=connectedorstatus=erroradded: your own https page (its origin must be on the key's embed origins), a page of the Lucra app (a path), orlucra-creators:for the Lucra iOS app. Defaults to a hosted done page (for stripe and card, the matching settings page).checkoutenumWith card or stripe. hosted (the default) returns Stripe's page at
url. With card, elements returnsclientSecretto save a new card in your own form with Stripe's Payment Element (Checkout elements, setup mode), which then replaces the card charged. With stripe, elements returnsclientSecretandcomponentfor Stripe's embedded Connect component (Connect.js): account_onboarding until identity is verified, then account_management. A Global Payouts creator has no embedded form:urlis Stripe's hosted page instead, withclientSecretnull.hostedelements
Response2014 fieldsShow
urlstringnullableSend the person here: they finish on the platform or Stripe, never on Lucra. The connection.connected (or creator.payouts_updated) webhook, or GET /v1/connections, shows the result. Null with
checkout: elements.clientSecretstringnullableWith
checkout: elements: for card, the Checkout Session's client secret for Stripe's Payment Element (initCheckoutElementsSdk; Stripe's setup webhook saves the card); for stripe, the account session's client secret for Connect.js (fetchClientSecret). Null otherwise.componentenumnullableWith stripe and
checkout: elements: the Connect embedded component to render with the client secret; null otherwise.account_onboardingaccount_managementexpiresAtstringnullableWhen the page stops working; null when it doesn't expire.
/v1/connections/:idPick a brand's ad account, page and identity after signing in, or disconnect a connection
const { data } = await lucra.connections.update({
path: { id: "conn_…" },
body: { status: "disconnected" },
})Path parameters
idconn_…· required
Body
statusstringDisconnects it: Lucra forgets the platform's tokens. An ad platform with live campaigns (see canDisconnect) is refused.
disconnectedselectionobjectA brand's ad platform picks, from GET /v1/connections/:id/setup: send the IDs it lists (e.g. adAccountId and pageId) to save them.
Show 8 child fieldsHide child fields
adAccountIdstringThe ad account campaigns run in (Meta, Google, Snapchat).
advertiserIdstringTikTok's advertiser account.
businessCenterIdstringTikTok's business center; send it to list the advertisers under it.
businessIdstringMeta's business; send it to list the ad accounts and pages under it.
identityIdstringThe TikTok identity ads post as.
organizationIdstringSnapchat's organization; send it to list its ad accounts.
pageIdstringThe Facebook page Meta ads post as.
profileIdstringSnapchat's public profile ads post as.
Response20012 fieldsShow
idconn_…providerenumThe platform connected.
metatiktokgooglesnapchatshopifyinstagramstatusstringThe platform connection's state, e.g. connected, active, expired; a shop is connected or reconnect_required.
namestringnullableThe ad account, the shop domain, or the creator's handle.
handlestringnullableA creator's handle on the platform; null for a brand's connections.
avatarUrlstringnullableA short-lived link to a creator account's profile photo.
lastSyncedAtstringnullableerrorstringnullableWhy a creator account's last sync failed, e.g. token_expired.
activeCampaignsintegerLive campaigns (or ones needing attention) on an ad platform connection. Campaigns only;
canDisconnectcovers every reason a disconnect is refused.canDisconnectbooleanWhether a disconnect would be accepted now: you manage the account's connections (or it's your own creator account), and no campaign, ad operation or ad plan is active on it.
createdAtstringupdatedAtstring
/v1/connections/:id/postsList the posts Lucra mirrors from a creator's connected account, newest first
const { data } = await lucra.connections.posts.list({
path: { id: "conn_…" },
})Path parameters
idconn_…· required
Response200A page of items, 12 fields each, and nextCursorShow
idstringThe post's ID on its platform.
platformenuminstagramtiktokurlstringnullabletitlestringnullablecaptionstringnullablepublishedAtstringnullabledurationLabelstringnullabledurationSecondsnumbernullablethumbnailUrlstringnullablevideoUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdstringnullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
metricsobjectnullableShow 6 child fieldsHide child fields
viewsnumberlikesnumbernullablecommentsnumbernullablesharesnumbernullablesavesnumbernullableengagementsnumbernullable
Creators
/v1/creatorsList the account's creators and, for a partner, its roster
const { data } = await lucra.creators.list({
query: { q: "…" },
})Query parameters
qstringMatches the name, email or a handle.
statusstringOne or more of invited, live, paused, review, removed; removed creators are left out unless asked for.
programprog_…Only creators approved into this program.
relationshipenumdirectrepresentedvisibilityenumprivatenetwork
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 32 fields each, and nextCursorShow
idcrtr_…namestringhandlestringnullableemailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe creator's picture, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
biostringnullablelocationstringnullableplatformHandlesobjectHandles by platform, e.g. { tiktok: "@sam" }.
tagsstring[]notesstringnullablestatusenumnullableThe creator's status with this account; null on a marketplace listing of a creator not in it.
invitedlivepausedreviewremovedrelationshipenumnullabledirect: in this account; represented: on a partner's roster; null on a marketplace listing of a creator not in it.
directrepresentedmanagedByacct_…nullablevisibilityenumprivate: hidden from brands' discovery; network: brands can find them.
privatenetworkchatAvailablebooleanprogramsprog_…[]Programs the creator is approved into in this account.
brandsacct_…[]A partner's roster creator: the client brands they work with through the partner.
retainerobjectnullableThe creator's open retainer with this account and its terms; GET /v1/retainers/:id has the rest.
Show 8 child fieldsHide child fields
idret_…statusenumofferedacceptedactivecancelingpayobjectShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
summarystringThe pay in plain English.
currencystringLowercase ISO 4217 code, e.g. usd.
deliverablesstringnullablenotesstringnullablecurrentPeriodEndAtstringnullable
payoutsobjectnullableWhere the creator is paid. To finish setup, send the creator to the URL from POST /v1/connections with provider: "stripe"; creator.payouts_updated fires when it changes. Null on a marketplace listing.
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
statsobjectShow 4 child fieldsHide child fields
approvedVideosintegerpendingVideosintegerapprovalRatenumberPercent of reviewed submissions approved.
installsinteger
tierenumThe tier the creator's XP reaches, Bronze to Diamond.
bronzesilvergoldplatinumdiamondperformanceobjectnullableDaily ad results of the creator's work and submissions approved each day, for this account; null outside its own creators.
Show 2 child fieldsHide child fields
currencystringLowercase ISO 4217 code, e.g. usd.
daysobject[]Show 7 child fieldsHide child fields
datestringspendintegerrevenueintegerclicksintegerimpressionsintegerpurchasesintegerapprovedSubmissionsinteger
referenceVideosobject[]Posts the creator shows brands, newest choice first.
Show 10 child fieldsHide child fields
platformenuminstagramtiktokuploadpoststringThe post's ID on its platform; for an
upload, the uploaded video'sfile_….filefile_…nullableurlstringnullabletitlestringnullablepublishedAtstringnullabledurationLabelstringnullablethumbnailUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
videoUrlstringnullable
takeRateobjectnullableA partner's roster creator: the partner's cut of their pay. Null elsewhere.
Show 2 child fieldsHide child fields
percentnumbercustombooleanSet for this creator alone; false follows the partner's default.
claimobjectnullableA partner's roster creator: whether they've claimed the account Lucra made for them. They claim it by signing in to Lucra with that email, verified.
Show 1 child fieldHide child fields
statusenuminvitedclaimed
listingobjectA marketplace listing's fields; only on GET /v1/marketplace/creators.
Show 12 child fieldsHide child fields
headlinestringnullablespecialtystringnullableagenumbernullablegenderstringnullablecategoriesstring[]creativeStylesstring[]interestsstring[]requestStatusenumnullableYour account's latest connection request to them.
pendingaccepteddeclinedaudiencestringnullablelastActivestringnullableresponseTimestringnullablesubmissionsobject[]Work the creator submitted on Lucra; on one creator's read.
Show 10 child fieldsHide child fields
idsub_…programNamestringnullableplatformenumnullableinstagramtiktokstatusenumapprovedliverejectedreviewrevisionsubmittedAtstringnullabledurationstringnullableformatstringnullablethumbnailUrlstringnullablevideoUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
profileobjectOnly when a creator reads themselves.
Show 8 child fieldsHide child fields
birthDatestringnullablegenderstringnullableinterestsstring[]creativeStylesstring[]locationDetailsobjectnullableShow 9 child fieldsHide child fields
citystringcountryCodestringcountryNamestringdisplayNamestringgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
onboardingCompletedAtstringnullablehiddenFromacct_…[]Partners that hide this creator from their Discover.
partnerFeeobjectnullableThe share of the creator's pay the partner representing them (
managedBy) takes, if any.Show 2 child fieldsHide child fields
partneracct_…percentnumber
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/creators/:idGet one of the account's creators, or, as a creator, yourself
const { data } = await lucra.creators.retrieve({
path: { id: "crtr_…" },
})Path parameters
idcrtr_…· required
Response20032 fieldsShow
idcrtr_…namestringhandlestringnullableemailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe creator's picture, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
biostringnullablelocationstringnullableplatformHandlesobjectHandles by platform, e.g. { tiktok: "@sam" }.
tagsstring[]notesstringnullablestatusenumnullableThe creator's status with this account; null on a marketplace listing of a creator not in it.
invitedlivepausedreviewremovedrelationshipenumnullabledirect: in this account; represented: on a partner's roster; null on a marketplace listing of a creator not in it.
directrepresentedmanagedByacct_…nullablevisibilityenumprivate: hidden from brands' discovery; network: brands can find them.
privatenetworkchatAvailablebooleanprogramsprog_…[]Programs the creator is approved into in this account.
brandsacct_…[]A partner's roster creator: the client brands they work with through the partner.
retainerobjectnullableThe creator's open retainer with this account and its terms; GET /v1/retainers/:id has the rest.
Show 8 child fieldsHide child fields
idret_…statusenumofferedacceptedactivecancelingpayobjectShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
summarystringThe pay in plain English.
currencystringLowercase ISO 4217 code, e.g. usd.
deliverablesstringnullablenotesstringnullablecurrentPeriodEndAtstringnullable
payoutsobjectnullableWhere the creator is paid. To finish setup, send the creator to the URL from POST /v1/connections with provider: "stripe"; creator.payouts_updated fires when it changes. Null on a marketplace listing.
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
statsobjectShow 4 child fieldsHide child fields
approvedVideosintegerpendingVideosintegerapprovalRatenumberPercent of reviewed submissions approved.
installsinteger
tierenumThe tier the creator's XP reaches, Bronze to Diamond.
bronzesilvergoldplatinumdiamondperformanceobjectnullableDaily ad results of the creator's work and submissions approved each day, for this account; null outside its own creators.
Show 2 child fieldsHide child fields
currencystringLowercase ISO 4217 code, e.g. usd.
daysobject[]Show 7 child fieldsHide child fields
datestringspendintegerrevenueintegerclicksintegerimpressionsintegerpurchasesintegerapprovedSubmissionsinteger
referenceVideosobject[]Posts the creator shows brands, newest choice first.
Show 10 child fieldsHide child fields
platformenuminstagramtiktokuploadpoststringThe post's ID on its platform; for an
upload, the uploaded video'sfile_….filefile_…nullableurlstringnullabletitlestringnullablepublishedAtstringnullabledurationLabelstringnullablethumbnailUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
videoUrlstringnullable
takeRateobjectnullableA partner's roster creator: the partner's cut of their pay. Null elsewhere.
Show 2 child fieldsHide child fields
percentnumbercustombooleanSet for this creator alone; false follows the partner's default.
claimobjectnullableA partner's roster creator: whether they've claimed the account Lucra made for them. They claim it by signing in to Lucra with that email, verified.
Show 1 child fieldHide child fields
statusenuminvitedclaimed
listingobjectA marketplace listing's fields; only on GET /v1/marketplace/creators.
Show 12 child fieldsHide child fields
headlinestringnullablespecialtystringnullableagenumbernullablegenderstringnullablecategoriesstring[]creativeStylesstring[]interestsstring[]requestStatusenumnullableYour account's latest connection request to them.
pendingaccepteddeclinedaudiencestringnullablelastActivestringnullableresponseTimestringnullablesubmissionsobject[]Work the creator submitted on Lucra; on one creator's read.
Show 10 child fieldsHide child fields
idsub_…programNamestringnullableplatformenumnullableinstagramtiktokstatusenumapprovedliverejectedreviewrevisionsubmittedAtstringnullabledurationstringnullableformatstringnullablethumbnailUrlstringnullablevideoUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
profileobjectOnly when a creator reads themselves.
Show 8 child fieldsHide child fields
birthDatestringnullablegenderstringnullableinterestsstring[]creativeStylesstring[]locationDetailsobjectnullableShow 9 child fieldsHide child fields
citystringcountryCodestringcountryNamestringdisplayNamestringgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
onboardingCompletedAtstringnullablehiddenFromacct_…[]Partners that hide this creator from their Discover.
partnerFeeobjectnullableThe share of the creator's pay the partner representing them (
managedBy) takes, if any.Show 2 child fieldsHide child fields
partneracct_…percentnumber
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/creatorsAdd a creator to a partner's roster; one already on it is returned with 200, and one with a Lucra account is invited (status invited) until they accept
const { data } = await lucra.creators.create({
body: { email: "…" },
})Body
emailstring· requirednamestringphonestringvisibilityenumprivatenetwork
Response20132 fieldsShow
idcrtr_…namestringhandlestringnullableemailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe creator's picture, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
biostringnullablelocationstringnullableplatformHandlesobjectHandles by platform, e.g. { tiktok: "@sam" }.
tagsstring[]notesstringnullablestatusenumnullableThe creator's status with this account; null on a marketplace listing of a creator not in it.
invitedlivepausedreviewremovedrelationshipenumnullabledirect: in this account; represented: on a partner's roster; null on a marketplace listing of a creator not in it.
directrepresentedmanagedByacct_…nullablevisibilityenumprivate: hidden from brands' discovery; network: brands can find them.
privatenetworkchatAvailablebooleanprogramsprog_…[]Programs the creator is approved into in this account.
brandsacct_…[]A partner's roster creator: the client brands they work with through the partner.
retainerobjectnullableThe creator's open retainer with this account and its terms; GET /v1/retainers/:id has the rest.
Show 8 child fieldsHide child fields
idret_…statusenumofferedacceptedactivecancelingpayobjectShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
summarystringThe pay in plain English.
currencystringLowercase ISO 4217 code, e.g. usd.
deliverablesstringnullablenotesstringnullablecurrentPeriodEndAtstringnullable
payoutsobjectnullableWhere the creator is paid. To finish setup, send the creator to the URL from POST /v1/connections with provider: "stripe"; creator.payouts_updated fires when it changes. Null on a marketplace listing.
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
statsobjectShow 4 child fieldsHide child fields
approvedVideosintegerpendingVideosintegerapprovalRatenumberPercent of reviewed submissions approved.
installsinteger
tierenumThe tier the creator's XP reaches, Bronze to Diamond.
bronzesilvergoldplatinumdiamondperformanceobjectnullableDaily ad results of the creator's work and submissions approved each day, for this account; null outside its own creators.
Show 2 child fieldsHide child fields
currencystringLowercase ISO 4217 code, e.g. usd.
daysobject[]Show 7 child fieldsHide child fields
datestringspendintegerrevenueintegerclicksintegerimpressionsintegerpurchasesintegerapprovedSubmissionsinteger
referenceVideosobject[]Posts the creator shows brands, newest choice first.
Show 10 child fieldsHide child fields
platformenuminstagramtiktokuploadpoststringThe post's ID on its platform; for an
upload, the uploaded video'sfile_….filefile_…nullableurlstringnullabletitlestringnullablepublishedAtstringnullabledurationLabelstringnullablethumbnailUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
videoUrlstringnullable
takeRateobjectnullableA partner's roster creator: the partner's cut of their pay. Null elsewhere.
Show 2 child fieldsHide child fields
percentnumbercustombooleanSet for this creator alone; false follows the partner's default.
claimobjectnullableA partner's roster creator: whether they've claimed the account Lucra made for them. They claim it by signing in to Lucra with that email, verified.
Show 1 child fieldHide child fields
statusenuminvitedclaimed
listingobjectA marketplace listing's fields; only on GET /v1/marketplace/creators.
Show 12 child fieldsHide child fields
headlinestringnullablespecialtystringnullableagenumbernullablegenderstringnullablecategoriesstring[]creativeStylesstring[]interestsstring[]requestStatusenumnullableYour account's latest connection request to them.
pendingaccepteddeclinedaudiencestringnullablelastActivestringnullableresponseTimestringnullablesubmissionsobject[]Work the creator submitted on Lucra; on one creator's read.
Show 10 child fieldsHide child fields
idsub_…programNamestringnullableplatformenumnullableinstagramtiktokstatusenumapprovedliverejectedreviewrevisionsubmittedAtstringnullabledurationstringnullableformatstringnullablethumbnailUrlstringnullablevideoUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
profileobjectOnly when a creator reads themselves.
Show 8 child fieldsHide child fields
birthDatestringnullablegenderstringnullableinterestsstring[]creativeStylesstring[]locationDetailsobjectnullableShow 9 child fieldsHide child fields
citystringcountryCodestringcountryNamestringdisplayNamestringgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
onboardingCompletedAtstringnullablehiddenFromacct_…[]Partners that hide this creator from their Discover.
partnerFeeobjectnullableThe share of the creator's pay the partner representing them (
managedBy) takes, if any.Show 2 child fieldsHide child fields
partneracct_…percentnumber
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/creators/:idUpdate a creator: a brand's labels and status, a partner's roster creator, or, as a creator, your own profile
const { data } = await lucra.creators.update({
path: { id: "crtr_…" },
body: { visibility: "private" },
})Path parameters
idcrtr_…· required
Body
visibilityenumprivatenetworkprofilePicturefile_…nullabletagsstring[]notesstringnullablestatusenumlivepausedremovedbrandsacct_…[]A partner's roster creator works with exactly these client brands; brands left out stop working with them.
takeRatenumbernullableA partner's roster creator: the partner's cut of their pay, as a percent, from now on; null puts them back on the partner's default.
biostringbirthDatestringnullablecreativeStylesenum[]product_demotestimonial_reviewtalking_headvoiceover_brolllifestyle_routineunboxingscreen_recordingcomedy_skitemailstringgenderenumnullablewomanmannonbinaryself_describeundisclosedhandlestringYour @handle, unique on Lucra: 1–30 letters, numbers, periods, underscores or hyphens. A leading @ is dropped and it is saved lowercase.
interestsenum[]fitnessbeautyfashionfood_drinktech_gamingtravelhome_diyparentingfinancewellnesspetscomedyeducationoutdoorsfitness_gymfitness_runningfitness_yogafitness_sportsbeauty_makeupbeauty_skincarebeauty_hairbeauty_nailsfashion_streetwearfashion_luxuryfashion_thriftfashion_menswearfood_drink_cookingfood_drink_bakingfood_drink_restaurantsfood_drink_coffeetech_gaming_gamingtech_gaming_gadgetstech_gaming_appstech_gaming_aitravel_budgettravel_luxurytravel_citytravel_adventurehome_diy_renovationhome_diy_decorhome_diy_gardeninghome_diy_organizationparenting_pregnancyparenting_babiesparenting_school_ageparenting_teensfinance_investingfinance_budgetingfinance_side_hustlesfinance_cryptowellness_mental_healthwellness_meditationwellness_nutritionwellness_sleeppets_dogspets_catspets_exoticpets_trainingcomedy_skitscomedy_prankscomedy_memescomedy_standupeducation_studyeducation_languageseducation_scienceeducation_historyoutdoors_campingoutdoors_hikingoutdoors_fishingoutdoors_climbinglocationstringlocationDetailsobjectnullableShow 9 child fieldsHide child fields
citystring· requiredcountryCodestring· requiredcountryNamestring· requireddisplayNamestring· requiredgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
namestringplatformHandlesobjectShow 2 child fieldsHide child fields
instagramstringtiktokstring
referenceVideoSelectionsobject[]Show 10 child fieldsHide child fields
durationLabelstringmediaAssetIdstringplatformenum· requiredinstagramtiktokuploadpublishedAtstringsourceContentIdstring· requiredsourceUrlstringthumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdstring· requiredurlstringwidthintegernullableheightintegernullableblurHashstringnullable
thumbnailUrlstringtitlestringvideoUrlstring
referenceVideosstring[]pictureFromenumUse this connected account's profile photo as the creator's picture.
instagramtiktokversioninteger
Response20032 fieldsShow
idcrtr_…namestringhandlestringnullableemailstringnullablephonestringnullableprofilePicturefile_…nullableimageobjectnullableThe creator's picture, with a short-lived
url.Show 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
biostringnullablelocationstringnullableplatformHandlesobjectHandles by platform, e.g. { tiktok: "@sam" }.
tagsstring[]notesstringnullablestatusenumnullableThe creator's status with this account; null on a marketplace listing of a creator not in it.
invitedlivepausedreviewremovedrelationshipenumnullabledirect: in this account; represented: on a partner's roster; null on a marketplace listing of a creator not in it.
directrepresentedmanagedByacct_…nullablevisibilityenumprivate: hidden from brands' discovery; network: brands can find them.
privatenetworkchatAvailablebooleanprogramsprog_…[]Programs the creator is approved into in this account.
brandsacct_…[]A partner's roster creator: the client brands they work with through the partner.
retainerobjectnullableThe creator's open retainer with this account and its terms; GET /v1/retainers/:id has the rest.
Show 8 child fieldsHide child fields
idret_…statusenumofferedacceptedactivecancelingpayobjectShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
summarystringThe pay in plain English.
currencystringLowercase ISO 4217 code, e.g. usd.
deliverablesstringnullablenotesstringnullablecurrentPeriodEndAtstringnullable
payoutsobjectnullableWhere the creator is paid. To finish setup, send the creator to the URL from POST /v1/connections with provider: "stripe"; creator.payouts_updated fires when it changes. Null on a marketplace listing.
Show 2 child fieldsHide child fields
identityobjectShow 1 child fieldHide child fields
statusenumrequiredpendingverified
bankAccountobjectnullableShow 1 child fieldHide child fields
statusenummissingadded
statsobjectShow 4 child fieldsHide child fields
approvedVideosintegerpendingVideosintegerapprovalRatenumberPercent of reviewed submissions approved.
installsinteger
tierenumThe tier the creator's XP reaches, Bronze to Diamond.
bronzesilvergoldplatinumdiamondperformanceobjectnullableDaily ad results of the creator's work and submissions approved each day, for this account; null outside its own creators.
Show 2 child fieldsHide child fields
currencystringLowercase ISO 4217 code, e.g. usd.
daysobject[]Show 7 child fieldsHide child fields
datestringspendintegerrevenueintegerclicksintegerimpressionsintegerpurchasesintegerapprovedSubmissionsinteger
referenceVideosobject[]Posts the creator shows brands, newest choice first.
Show 10 child fieldsHide child fields
platformenuminstagramtiktokuploadpoststringThe post's ID on its platform; for an
upload, the uploaded video'sfile_….filefile_…nullableurlstringnullabletitlestringnullablepublishedAtstringnullabledurationLabelstringnullablethumbnailUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
videoUrlstringnullable
takeRateobjectnullableA partner's roster creator: the partner's cut of their pay. Null elsewhere.
Show 2 child fieldsHide child fields
percentnumbercustombooleanSet for this creator alone; false follows the partner's default.
claimobjectnullableA partner's roster creator: whether they've claimed the account Lucra made for them. They claim it by signing in to Lucra with that email, verified.
Show 1 child fieldHide child fields
statusenuminvitedclaimed
listingobjectA marketplace listing's fields; only on GET /v1/marketplace/creators.
Show 12 child fieldsHide child fields
headlinestringnullablespecialtystringnullableagenumbernullablegenderstringnullablecategoriesstring[]creativeStylesstring[]interestsstring[]requestStatusenumnullableYour account's latest connection request to them.
pendingaccepteddeclinedaudiencestringnullablelastActivestringnullableresponseTimestringnullablesubmissionsobject[]Work the creator submitted on Lucra; on one creator's read.
Show 10 child fieldsHide child fields
idsub_…programNamestringnullableplatformenumnullableinstagramtiktokstatusenumapprovedliverejectedreviewrevisionsubmittedAtstringnullabledurationstringnullableformatstringnullablethumbnailUrlstringnullablevideoUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
profileobjectOnly when a creator reads themselves.
Show 8 child fieldsHide child fields
birthDatestringnullablegenderstringnullableinterestsstring[]creativeStylesstring[]locationDetailsobjectnullableShow 9 child fieldsHide child fields
citystringcountryCodestringcountryNamestringdisplayNamestringgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
onboardingCompletedAtstringnullablehiddenFromacct_…[]Partners that hide this creator from their Discover.
partnerFeeobjectnullableThe share of the creator's pay the partner representing them (
managedBy) takes, if any.Show 2 child fieldsHide child fields
partneracct_…percentnumber
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Files
/v1/filesUpload a file
const { data } = await lucra.files.create({
query: { purpose: "submission" },
body: file,
})Query parameters
purposeenum· requiredsubmissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnailnamestringsizeintegerReserve instead of streaming: the file's size in bytes. The body stays empty.
contentTypestringWith
size: the file's MIME type.checksumstringWith
size: the file's SHA-256 (lowercase hex). Storage then checks the bytes as they arrive, so finishing a video is quicker.ownerstringWith purpose=profile_picture: the signed-in person's own photo, for PATCH /v1/me.
me
Body
The file's raw bytes.
Response20115 fieldsShow
idfile_…purposeenumsubmissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnailstatusenumawaiting_upload: reserved, waiting for the bytes at
upload.url; processing: being verified or prepared; failed carries why.awaiting_uploadprocessingreadyfaileddeletedfileNamestringnullablecontentTypestringnullablesizenumbernullableurlstringnullableA signed link to the file, valid for about 10 minutes; null until it's ready.
widthnumbernullableheightnumbernullableblurHashstringnullableAn image's blur-hash placeholder, once computed.
errorobjectnullableWhy it failed;
upload_incompletewhen the upload was cut off.Show 2 child fieldsHide child fields
codestringmessagestring
uploadobjectWhere to PUT the bytes, with these headers, before
expiresAt; only on a reservation.Show 3 child fieldsHide child fields
urlstringheadersobjectexpiresAtstring
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/filesList files
const { data } = await lucra.files.list({
query: { purpose: "…" },
})Query parameters
purposestringOne or more, comma-separated: submission, product_image, profile_picture, program_brief, program_reference_video, agreement, chat_attachment, ad_creative, profile_reference, profile_reference_thumbnail.
statusstringOne or more, comma-separated: awaiting_upload, processing, ready, failed, deleted.
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 15 fields each, and nextCursorShow
idfile_…purposeenumsubmissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnailstatusenumawaiting_upload: reserved, waiting for the bytes at
upload.url; processing: being verified or prepared; failed carries why.awaiting_uploadprocessingreadyfaileddeletedfileNamestringnullablecontentTypestringnullablesizenumbernullableurlstringnullableA signed link to the file, valid for about 10 minutes; null until it's ready.
widthnumbernullableheightnumbernullableblurHashstringnullableAn image's blur-hash placeholder, once computed.
errorobjectnullableWhy it failed;
upload_incompletewhen the upload was cut off.Show 2 child fieldsHide child fields
codestringmessagestring
uploadobjectWhere to PUT the bytes, with these headers, before
expiresAt; only on a reservation.Show 3 child fieldsHide child fields
urlstringheadersobjectexpiresAtstring
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/files/:idGet a file
const { data } = await lucra.files.retrieve({
path: { id: "file_…" },
})Path parameters
idfile_…· required
Response20015 fieldsShow
idfile_…purposeenumsubmissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnailstatusenumawaiting_upload: reserved, waiting for the bytes at
upload.url; processing: being verified or prepared; failed carries why.awaiting_uploadprocessingreadyfaileddeletedfileNamestringnullablecontentTypestringnullablesizenumbernullableurlstringnullableA signed link to the file, valid for about 10 minutes; null until it's ready.
widthnumbernullableheightnumbernullableblurHashstringnullableAn image's blur-hash placeholder, once computed.
errorobjectnullableWhy it failed;
upload_incompletewhen the upload was cut off.Show 2 child fieldsHide child fields
codestringmessagestring
uploadobjectWhere to PUT the bytes, with these headers, before
expiresAt; only on a reservation.Show 3 child fieldsHide child fields
urlstringheadersobjectexpiresAtstring
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/files/:idFinish or delete an upload
const { data } = await lucra.files.update({
path: { id: "file_…" },
body: { status: "processing" },
})Path parameters
idfile_…· required
Body
statusenum· requiredprocessing: the bytes are at
upload.url, so verify and store them (images are then ready at once); deleted: cancel the upload, or delete a file nothing uses.processingdeleted
Response20015 fieldsShow
idfile_…purposeenumsubmissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnailstatusenumawaiting_upload: reserved, waiting for the bytes at
upload.url; processing: being verified or prepared; failed carries why.awaiting_uploadprocessingreadyfaileddeletedfileNamestringnullablecontentTypestringnullablesizenumbernullableurlstringnullableA signed link to the file, valid for about 10 minutes; null until it's ready.
widthnumbernullableheightnumbernullableblurHashstringnullableAn image's blur-hash placeholder, once computed.
errorobjectnullableWhy it failed;
upload_incompletewhen the upload was cut off.Show 2 child fieldsHide child fields
codestringmessagestring
uploadobjectWhere to PUT the bytes, with these headers, before
expiresAt; only on a reservation.Show 3 child fieldsHide child fields
urlstringheadersobjectexpiresAtstring
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Messages
/v1/messagesList messages
const { data } = await lucra.messages.list({
query: { thread: "thr_…" },
})Response200A page of items, 12 fields each, and nextCursorShow
idstringthreadstringsenderobjectShow 4 child fieldsHide child fields
idstringtypeenumorganizationcreatorsupportnamestringnullableavatarstringnullable
automatedbooleanbodystringfilesobject[]Show 8 child fieldsHide child fields
idstringnamestringkindenumimagevideodocumentsizenumbernullablewidthnumbernullableheightnumbernullableurlstringnullablethumbnailUrlstringnullable
replyTostringnullablereactionsobject[]Show 2 child fieldsHide child fields
emojistringactorsstring[]
createdAtstringeditedAtstringnullabledeletedAtstringnullableversioninteger
/v1/messagesSend a message
const { data } = await lucra.messages.create({
body: { thread: "thr_…" },
})Body
threadthr_…· requiredbodystringfilesfile_…[]Attachments:
chat_attachmentfiles.replyTomsg_…
Response20112 fieldsShow
idstringthreadstringsenderobjectShow 4 child fieldsHide child fields
idstringtypeenumorganizationcreatorsupportnamestringnullableavatarstringnullable
automatedbooleanbodystringfilesobject[]Show 8 child fieldsHide child fields
idstringnamestringkindenumimagevideodocumentsizenumbernullablewidthnumbernullableheightnumbernullableurlstringnullablethumbnailUrlstringnullable
replyTostringnullablereactionsobject[]Show 2 child fieldsHide child fields
emojistringactorsstring[]
createdAtstringeditedAtstringnullabledeletedAtstringnullableversioninteger
/v1/messages/:idEdit or delete a message the caller sent (at its version), react to a message, or report it; one change per request
const { data } = await lucra.messages.update({
path: { id: "…" },
body: { version: 1000 },
})Path parameters
idstring· required
Body
versionintegerThe message's
versionas read; required to edit or delete.bodystringNew text for a message the caller sent.
statusstringDelete a message the caller sent.
deletedreactionobjectAdd or remove the caller's emoji reaction.
Show 2 child fieldsHide child fields
emojistring· requiredactiveboolean· requiredtrue adds the reaction, false removes it.
reportobjectReport the message to Lucra.
Show 2 child fieldsHide child fields
reasonenum· requiredspamharassmentunsafe_contentotherdetailstring
Response20012 fieldsShow
idstringthreadstringsenderobjectShow 4 child fieldsHide child fields
idstringtypeenumorganizationcreatorsupportnamestringnullableavatarstringnullable
automatedbooleanbodystringfilesobject[]Show 8 child fieldsHide child fields
idstringnamestringkindenumimagevideodocumentsizenumbernullablewidthnumbernullableheightnumbernullableurlstringnullablethumbnailUrlstringnullable
replyTostringnullablereactionsobject[]Show 2 child fieldsHide child fields
emojistringactorsstring[]
createdAtstringeditedAtstringnullabledeletedAtstringnullableversioninteger
Payments
/v1/paymentsPay a creator
const { data } = await lucra.payments.create({
body: { creator: "crtr_…", net: 1000 },
})Headers
Idempotency-Keystring· requiredUnique to this write; resend it to retry safely.
Body
creatorcrtr_…· requirednetinteger· requiredIn cents, what the creator receives and the brand is charged.
notestring
Response20115 fieldsShow
idpay_…creatorcrtr_…amountintegerCharged to the brand: what the creator receives (
net; Lucra takes no fee), in cents.feeintegerTaken from
amount, in cents.netintegeramountlessfee, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with
failureMessage. disputed until Lucra decides; refunded if canceled.pending_approvalapprovedpendingsucceededfailedrefundeddisputedretainerret_…nullableThe retainer this is a period payment of, if any.
failureMessagestringnullablenotestringnullableholdUntilAtstringnullabledisputeobjectnullableWhile
statusis disputed: who opened it and why; null otherwise.Show 3 child fieldsHide child fields
byenumbrand: the paying brand disputed it; lucra: Lucra holds it for review.
brandlucrareasonstringnullableWhy; a Lucra hold's reason shows only to Lucra's admin.
openedAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/paymentsList payments to creators
const { data } = await lucra.payments.list({
query: { creator: "crtr_…" },
})Query parameters
creatorcrtr_…retainerret_…statusenumpending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with
failureMessage. disputed until Lucra decides; refunded if canceled.pending_approvalapprovedpendingsucceededfailedrefundeddisputed
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 15 fields each, and nextCursorShow
idpay_…creatorcrtr_…amountintegerCharged to the brand: what the creator receives (
net; Lucra takes no fee), in cents.feeintegerTaken from
amount, in cents.netintegeramountlessfee, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with
failureMessage. disputed until Lucra decides; refunded if canceled.pending_approvalapprovedpendingsucceededfailedrefundeddisputedretainerret_…nullableThe retainer this is a period payment of, if any.
failureMessagestringnullablenotestringnullableholdUntilAtstringnullabledisputeobjectnullableWhile
statusis disputed: who opened it and why; null otherwise.Show 3 child fieldsHide child fields
byenumbrand: the paying brand disputed it; lucra: Lucra holds it for review.
brandlucrareasonstringnullableWhy; a Lucra hold's reason shows only to Lucra's admin.
openedAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/payments/:idGet a payment to a creator
const { data } = await lucra.payments.retrieve({
path: { id: "pay_…" },
})Path parameters
idpay_…· required
Response20015 fieldsShow
idpay_…creatorcrtr_…amountintegerCharged to the brand: what the creator receives (
net; Lucra takes no fee), in cents.feeintegerTaken from
amount, in cents.netintegeramountlessfee, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with
failureMessage. disputed until Lucra decides; refunded if canceled.pending_approvalapprovedpendingsucceededfailedrefundeddisputedretainerret_…nullableThe retainer this is a period payment of, if any.
failureMessagestringnullablenotestringnullableholdUntilAtstringnullabledisputeobjectnullableWhile
statusis disputed: who opened it and why; null otherwise.Show 3 child fieldsHide child fields
byenumbrand: the paying brand disputed it; lucra: Lucra holds it for review.
brandlucrareasonstringnullableWhy; a Lucra hold's reason shows only to Lucra's admin.
openedAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/payments/:idApprove or dispute a payment to a creator
const { data } = await lucra.payments.update({
path: { id: "pay_…" },
body: { },
})Path parameters
idpay_…· required
Headers
Idempotency-Keystring· requiredUnique to this write; resend it to retry safely.
Response20015 fieldsShow
idpay_…creatorcrtr_…amountintegerCharged to the brand: what the creator receives (
net; Lucra takes no fee), in cents.feeintegerTaken from
amount, in cents.netintegeramountlessfee, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpending_approval until the brand approves it, then approved while it's charged; pending until Stripe confirms the charge; then succeeded, or failed with
failureMessage. disputed until Lucra decides; refunded if canceled.pending_approvalapprovedpendingsucceededfailedrefundeddisputedretainerret_…nullableThe retainer this is a period payment of, if any.
failureMessagestringnullablenotestringnullableholdUntilAtstringnullabledisputeobjectnullableWhile
statusis disputed: who opened it and why; null otherwise.Show 3 child fieldsHide child fields
byenumbrand: the paying brand disputed it; lucra: Lucra holds it for review.
brandlucrareasonstringnullableWhy; a Lucra hold's reason shows only to Lucra's admin.
openedAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Payouts
/v1/payouts/countriesThe payout countries that can be chosen now: a creator's (Stripe Global Payouts' too while it's on), or this brand's or partner's
const { data } = await lucra.payouts.countries.retrieve()Response2001 fieldsShow
countriesenum[]The payout countries that can be chosen now. Stripe Global Payouts countries appear only while Lucra has them switched on; brands and partners get Stripe Connect's only.
ATBEBGCAHRCYCZDKEEFIFRDEGRHUISIEITLVLILTLUMTNLNOPLPTROSKSIESSECHGBUSAUINIDILJPJMMXMCMANZSMSGTT
/v1/payoutsList payouts: to creators from this brand's earnings, received by this account, or (as a creator) the creator's own
const { data } = await lucra.payouts.list({
query: { direction: "sent" },
})Query parameters
directionenumsentreceivedcreatorcrtr_…statusstringOne or more, comma-separated: pending, submitted, paid, failed, reversed, unknown.
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 12 fields each, and nextCursorShow
idpout_…directionenumsent: from this brand's earnings to a creator's balance; received: paid to this account's balance, like a partner's commission.
sentreceivedcreatorcrtr_…nullablesourcesenum[]paid_adsorganicsubmissionprogrambonusretainerreferraladjustmentpartner_commissionamountintegerThe earnings it pays;
netis sent to the recipient's Stripe balance, in cents.feeintegerTaken from
amount, in cents.netintegeramountlessfee, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpendingsubmittedpaidfailedreversedunknownfailureMessagestringnullablecreatedAtstringupdatedAtstring
/v1/payouts/:idGet a payout
const { data } = await lucra.payouts.retrieve({
path: { id: "pout_…" },
})Path parameters
idpout_…· required
Response20012 fieldsShow
idpout_…directionenumsent: from this brand's earnings to a creator's balance; received: paid to this account's balance, like a partner's commission.
sentreceivedcreatorcrtr_…nullablesourcesenum[]paid_adsorganicsubmissionprogrambonusretainerreferraladjustmentpartner_commissionamountintegerThe earnings it pays;
netis sent to the recipient's Stripe balance, in cents.feeintegerTaken from
amount, in cents.netintegeramountlessfee, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpendingsubmittedpaidfailedreversedunknownfailureMessagestringnullablecreatedAtstringupdatedAtstring
Earnings
/v1/earningsList a creator's earnings
const { data } = await lucra.earnings.list({
query: { status: "…" },
})Query parameters
statusstringOne or more, comma-separated: pending, held, available, paid.
sourcestringOne or more, comma-separated: paid_ads, organic, submission, program, bonus, retainer, referral, adjustment, partner_commission.
programprog_…retainerret_…
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 13 fields each, and nextCursorShow
idern_…programprog_…nullableaccountacct_…The brand that paid it.
submissionsub_…nullableretainerret_…nullablesourceenumpaid_adsorganicsubmissionprogrambonusretainerreferraladjustmentpartner_commissionamountintegerEarned before any partner take rate (
fee); the creator receivesnet, in cents.feeintegerTaken from
amount, in cents.netintegeramountlessfee, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpending until the brand's charge succeeds, then available, then paid: sent to the creator's Stripe balance against that charge (once their identity is verified), paid out to their bank weekly or withdrawn anytime. held while a dispute is reviewed, or a referral waits on the payment it comes from.
pendingheldavailablepaidholdUntilAtstringnullableoccurredAtstring
/v1/earnings/:idGet one of a creator's earnings
const { data } = await lucra.earnings.retrieve({
path: { id: "ern_…" },
})Path parameters
idern_…· required
Response20013 fieldsShow
idern_…programprog_…nullableaccountacct_…The brand that paid it.
submissionsub_…nullableretainerret_…nullablesourceenumpaid_adsorganicsubmissionprogrambonusretainerreferraladjustmentpartner_commissionamountintegerEarned before any partner take rate (
fee); the creator receivesnet, in cents.feeintegerTaken from
amount, in cents.netintegeramountlessfee, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpending until the brand's charge succeeds, then available, then paid: sent to the creator's Stripe balance against that charge (once their identity is verified), paid out to their bank weekly or withdrawn anytime. held while a dispute is reviewed, or a referral waits on the payment it comes from.
pendingheldavailablepaidholdUntilAtstringnullableoccurredAtstring
Withdrawals
/v1/withdrawalsWithdraw from the balance to the bank account or debit card (not for Global Payouts creators, paid every Monday)
const { data } = await lucra.withdrawals.create({
body: { amount: 1000 },
})Headers
Idempotency-Keystring· requiredUnique to this write; resend it to retry safely.
Body
amountintegerIn cents; defaults to everything withdrawable.
speedenumstandardinstant
Response20111 fieldsShow
idwdr_…amountintegerTaken from the balance, in cents.
feeintegerLucra's fee, taken from the amount: the instant fee, plus the cross-border fee outside the US.
netintegeramountlessfee: what reaches the bank or card, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
speedenumstandardinstantstatusenumin_transit once Stripe accepted it; paid when it reached the bank.
pendingin_transitpaidfailedfailureMessagestringnullablearrivesAtstringnullablecreatedAtstringupdatedAtstring
/v1/withdrawalsList withdrawals from the balance, or a Global Payouts creator's weekly payouts
const { data } = await lucra.withdrawals.list({
query: { status: "…" },
})Query parameters
statusstringOne or more, comma-separated: pending, in_transit, paid, failed.
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 11 fields each, and nextCursorShow
idwdr_…amountintegerTaken from the balance, in cents.
feeintegerLucra's fee, taken from the amount: the instant fee, plus the cross-border fee outside the US.
netintegeramountlessfee: what reaches the bank or card, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
speedenumstandardinstantstatusenumin_transit once Stripe accepted it; paid when it reached the bank.
pendingin_transitpaidfailedfailureMessagestringnullablearrivesAtstringnullablecreatedAtstringupdatedAtstring
/v1/withdrawals/:idGet a withdrawal
const { data } = await lucra.withdrawals.retrieve({
path: { id: "wdr_…" },
})Path parameters
idwdr_…· required
Response20011 fieldsShow
idwdr_…amountintegerTaken from the balance, in cents.
feeintegerLucra's fee, taken from the amount: the instant fee, plus the cross-border fee outside the US.
netintegeramountlessfee: what reaches the bank or card, in cents.currencystringLowercase ISO 4217 code, e.g. usd.
speedenumstandardinstantstatusenumin_transit once Stripe accepted it; paid when it reached the bank.
pendingin_transitpaidfailedfailureMessagestringnullablearrivesAtstringnullablecreatedAtstringupdatedAtstring
Cities
/v1/citiesSearch cities by name, exact matches first
const { data } = await lucra.cities.list({
query: { q: "…" },
})Query parameters
qstring· requiredA city name, or the start of one.
countrystringOnly cities in this country (ISO 3166-1 alpha-2, e.g. US).
limitintegerCities per page.
cursorstringnextCursorfrom the previous page, with the same q and country.
Response200A page of items, 12 fields each, and nextCursorShow
geonamesIdstringnamestringdisplayNamestringcitystringregionstringnullableregionCodestringnullableregionNamestringnullablecountryCodestringcountryNamestringlatitudenumberlongitudenumbertimeZonestring
Keys
/v1/keys/currentGet the calling key's webhook URL
const { data } = await lucra.keys.current.retrieve()Response2003 fieldsShow
keykey_…webhookUrlstringnullableWhere this key's events are POSTed; null sends none.
webhookSecretstringnullableThe secret that signs
Lucra-Signature, shown once: when a URL is set. Null otherwise.
/v1/keys/currentSet or clear the calling key's webhook URL; setting one issues a new signing secret, in this response only
const { data } = await lucra.keys.current.update({
body: { webhookUrl: "…" },
})Body
webhookUrlstringnullable· requiredA public https:// URL to POST this key's events to, or null to stop sending them.
Response2003 fieldsShow
keykey_…webhookUrlstringnullableWhere this key's events are POSTed; null sends none.
webhookSecretstringnullableThe secret that signs
Lucra-Signature, shown once: when a URL is set. Null otherwise.
Events
/v1/eventsList the events sent to this key's webhook, newest first, to replay missed ones
const { data } = await lucra.events.list()Query parameters
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 6 fields each, and nextCursorShow
idevt_…typestring<resource>.<past tense>, as the webhook names it.createdAtstringaccountacct_…nullabledataobjectIDs of the records involved, keyed by kind, e.g. { creator: "crtr_…" }.
deliveryenumWhether the POST to the webhook URL succeeded; failed after three days of retries.
pendingdeliveredfailed
Agreements
/v1/agreements/acceptancesList creators' acceptances of your agreements; as a creator, the ones you accepted and the ones waiting on you
const { data } = await lucra.agreements.acceptances.list({
query: { agreement: "agr_…" },
})Query parameters
agreementagr_…creatorcrtr_…statusenumpending: offers and invitations waiting on a creator; only a creator lists these.
acceptedpending
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 13 fields each, and nextCursorShow
idagac_…statusenumacceptedpendingaccountacct_…The brand whose agreement it is.
brandNamestringcreatorcrtr_…creatorNamestringnullablecontextenumcreator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissionprogramprog_…nullableretainerret_…nullabletitlestringdocumentanynullableThe version accepted; null while pending.
acceptedAtstringnullablecreatedAtstring
/v1/agreementsList agreements
const { data } = await lucra.agreements.list({
query: { status: "…" },
})Query parameters
statusstringOne or more, comma-separated: active, archived.
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 11 fields each, and nextCursorShow
idagr_…titlestringdescriptionstringnullablestatusenumactivearchivedapplicabilityenum[]Where every creator must accept it: creator_relationship, program_application, program_enrollment, retainer or content_submission.
creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissionlatestVersionobjectnullableEvery version: GET /v1/agreements/:id/versions.
Show 9 child fieldsHide child fields
agreementagr_…versionintegerfilefile_…nullablefileNamestringsizeintegersha256stringapplicabilityenum[]creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissioncreatedAtstringurlstringnullableA short-lived link to the PDF.
acceptedCountintegerCreators who accepted a version; each acceptance: GET /v1/agreements/acceptances?agreement=…
pendingCountintegerversionintegerSend it back as
versionto reject a change based on a stale read.createdAtstringupdatedAtstring
/v1/agreements/:idGet an agreement
const { data } = await lucra.agreements.retrieve({
path: { id: "agr_…" },
})Path parameters
idagr_…· required
Response20011 fieldsShow
idagr_…titlestringdescriptionstringnullablestatusenumactivearchivedapplicabilityenum[]Where every creator must accept it: creator_relationship, program_application, program_enrollment, retainer or content_submission.
creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissionlatestVersionobjectnullableEvery version: GET /v1/agreements/:id/versions.
Show 9 child fieldsHide child fields
agreementagr_…versionintegerfilefile_…nullablefileNamestringsizeintegersha256stringapplicabilityenum[]creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissioncreatedAtstringurlstringnullableA short-lived link to the PDF.
acceptedCountintegerCreators who accepted a version; each acceptance: GET /v1/agreements/acceptances?agreement=…
pendingCountintegerversionintegerSend it back as
versionto reject a change based on a stale read.createdAtstringupdatedAtstring
/v1/agreements/:id/versionsList an agreement's versions, newest first
const { data } = await lucra.agreements.versions.list({
path: { id: "agr_…" },
})Path parameters
idagr_…· required
Query parameters
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 9 fields each, and nextCursorShow
agreementagr_…versionintegerfilefile_…nullablefileNamestringsizeintegersha256stringapplicabilityenum[]creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissioncreatedAtstringurlstringnullableA short-lived link to the PDF.
/v1/agreements/:id/versions/:numberGet a version of an agreement by its number
const { data } = await lucra.agreements.versions.retrieve({
path: { id: "agr_…", number: "…" },
})Path parameters
idagr_…· requirednumberstring· required
Response2009 fieldsShow
agreementagr_…versionintegerfilefile_…nullablefileNamestringsizeintegersha256stringapplicabilityenum[]creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissioncreatedAtstringurlstringnullableA short-lived link to the PDF.
/v1/agreementsPublish an agreement
const { data } = await lucra.agreements.create({
body: { file: "file_…", title: "…" },
})Body
filefile_…· requiredA ready PDF uploaded with POST /v1/files?purpose=agreement.
titlestring· requireddescriptionstringnullableapplicabilityenum[]Where every creator must accept it; empty (the default) for an agreement only the programs that list it require.
creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submission
Response20111 fieldsShow
idagr_…titlestringdescriptionstringnullablestatusenumactivearchivedapplicabilityenum[]Where every creator must accept it: creator_relationship, program_application, program_enrollment, retainer or content_submission.
creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissionlatestVersionobjectnullableEvery version: GET /v1/agreements/:id/versions.
Show 9 child fieldsHide child fields
agreementagr_…versionintegerfilefile_…nullablefileNamestringsizeintegersha256stringapplicabilityenum[]creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissioncreatedAtstringurlstringnullableA short-lived link to the PDF.
acceptedCountintegerCreators who accepted a version; each acceptance: GET /v1/agreements/acceptances?agreement=…
pendingCountintegerversionintegerSend it back as
versionto reject a change based on a stale read.createdAtstringupdatedAtstring
/v1/agreements/:id/versionsPublish a new version of an agreement
const { data } = await lucra.agreements.versions.create({
path: { id: "agr_…" },
body: { file: "file_…", title: "…" },
})Path parameters
idagr_…· required
Body
filefile_…· requiredA ready PDF uploaded with POST /v1/files?purpose=agreement.
titlestring· requireddescriptionstringnullableapplicabilityenum[]Where every creator must accept it; empty (the default) for an agreement only the programs that list it require.
creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissionversioninteger
Response20111 fieldsShow
idagr_…titlestringdescriptionstringnullablestatusenumactivearchivedapplicabilityenum[]Where every creator must accept it: creator_relationship, program_application, program_enrollment, retainer or content_submission.
creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissionlatestVersionobjectnullableEvery version: GET /v1/agreements/:id/versions.
Show 9 child fieldsHide child fields
agreementagr_…versionintegerfilefile_…nullablefileNamestringsizeintegersha256stringapplicabilityenum[]creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissioncreatedAtstringurlstringnullableA short-lived link to the PDF.
acceptedCountintegerCreators who accepted a version; each acceptance: GET /v1/agreements/acceptances?agreement=…
pendingCountintegerversionintegerSend it back as
versionto reject a change based on a stale read.createdAtstringupdatedAtstring
/v1/agreements/:idChange where an agreement is required, or archive it
const { data } = await lucra.agreements.update({
path: { id: "agr_…" },
body: { applicability: ["creator_relationship"] },
})Path parameters
idagr_…· required
Body
applicabilityenum[]creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissionstatusstringarchivedversioninteger
Response20011 fieldsShow
idagr_…titlestringdescriptionstringnullablestatusenumactivearchivedapplicabilityenum[]Where every creator must accept it: creator_relationship, program_application, program_enrollment, retainer or content_submission.
creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissionlatestVersionobjectnullableEvery version: GET /v1/agreements/:id/versions.
Show 9 child fieldsHide child fields
agreementagr_…versionintegerfilefile_…nullablefileNamestringsizeintegersha256stringapplicabilityenum[]creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissioncreatedAtstringurlstringnullableA short-lived link to the PDF.
acceptedCountintegerCreators who accepted a version; each acceptance: GET /v1/agreements/acceptances?agreement=…
pendingCountintegerversionintegerSend it back as
versionto reject a change based on a stale read.createdAtstringupdatedAtstring
Threads
/v1/threadsList the conversations the account (or, acting as a creator, the creator) takes part in, most recently active first
const { data } = await lucra.threads.list({
query: { kind: "direct" },
})Query parameters
kindenumdirectprogramsupportprogramprog_…
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 15 fields each, and nextCursorShow
idstringkindenumdirectprogramsupportaccountstringnullableprogramstringnullableprogramNamestringnullablesupportobjectnullableShow 2 child fieldsHide child fields
statusenumwaiting_on_lucrawaiting_on_customerresolvedresolvedAtstringnullable
participantsobject[]Show 3 child fieldsHide child fields
actorobjectShow 4 child fieldsHide child fields
idstringtypeenumorganizationcreatorsupportnamestringnullableavatarstringnullable
lastReadstringnullablejoinedAtstring
lastMessageobjectnullableShow 12 child fieldsHide child fields
idstringthreadstringsenderobjectShow 4 child fieldsHide child fields
idstringtypeenumorganizationcreatorsupportnamestringnullableavatarstringnullable
automatedbooleanbodystringfilesobject[]Show 8 child fieldsHide child fields
idstringnamestringkindenumimagevideodocumentsizenumbernullablewidthnumbernullableheightnumbernullableurlstringnullablethumbnailUrlstringnullable
replyTostringnullablereactionsobject[]Show 2 child fieldsHide child fields
emojistringactorsstring[]
createdAtstringeditedAtstringnullabledeletedAtstringnullableversioninteger
mutedbooleanblockedstring[]canSendbooleanunreadCountintegercreatedAtstringupdatedAtstringversioninteger
/v1/threadsOpen a direct conversation with an account or creator you work with (an account can also message any creator it finds in the marketplace), a program's group chat or a Lucra Support thread; an existing one is returned
const { data } = await lucra.threads.create({
body: { kind: "direct" },
})Body
kindenum· requireddirect: one account or creator; program: a program's group chat; support: Lucra Support.
directprogramsupportwithstringdirect: the account (acct_) or creator (crtr_) to talk to; a creator must work with the account (and the reverse).
programstringprogram: the program (prog_) whose group chat to open.
messageobjectA first message, sent when the conversation is new.
Show 2 child fieldsHide child fields
bodystringThe message text.
filesstring[]Attachments:
chat_attachmentfiles (file_).
Response20115 fieldsShow
idstringkindenumdirectprogramsupportaccountstringnullableprogramstringnullableprogramNamestringnullablesupportobjectnullableShow 2 child fieldsHide child fields
statusenumwaiting_on_lucrawaiting_on_customerresolvedresolvedAtstringnullable
participantsobject[]Show 3 child fieldsHide child fields
actorobjectShow 4 child fieldsHide child fields
idstringtypeenumorganizationcreatorsupportnamestringnullableavatarstringnullable
lastReadstringnullablejoinedAtstring
lastMessageobjectnullableShow 12 child fieldsHide child fields
idstringthreadstringsenderobjectShow 4 child fieldsHide child fields
idstringtypeenumorganizationcreatorsupportnamestringnullableavatarstringnullable
automatedbooleanbodystringfilesobject[]Show 8 child fieldsHide child fields
idstringnamestringkindenumimagevideodocumentsizenumbernullablewidthnumbernullableheightnumbernullableurlstringnullablethumbnailUrlstringnullable
replyTostringnullablereactionsobject[]Show 2 child fieldsHide child fields
emojistringactorsstring[]
createdAtstringeditedAtstringnullabledeletedAtstringnullableversioninteger
mutedbooleanblockedstring[]canSendbooleanunreadCountintegercreatedAtstringupdatedAtstringversioninteger
/v1/threads/:idGet a conversation; its messages are GET /v1/messages?thread=
const { data } = await lucra.threads.retrieve({
path: { id: "…" },
})Path parameters
idstring· required
Response20015 fieldsShow
idstringkindenumdirectprogramsupportaccountstringnullableprogramstringnullableprogramNamestringnullablesupportobjectnullableShow 2 child fieldsHide child fields
statusenumwaiting_on_lucrawaiting_on_customerresolvedresolvedAtstringnullable
participantsobject[]Show 3 child fieldsHide child fields
actorobjectShow 4 child fieldsHide child fields
idstringtypeenumorganizationcreatorsupportnamestringnullableavatarstringnullable
lastReadstringnullablejoinedAtstring
lastMessageobjectnullableShow 12 child fieldsHide child fields
idstringthreadstringsenderobjectShow 4 child fieldsHide child fields
idstringtypeenumorganizationcreatorsupportnamestringnullableavatarstringnullable
automatedbooleanbodystringfilesobject[]Show 8 child fieldsHide child fields
idstringnamestringkindenumimagevideodocumentsizenumbernullablewidthnumbernullableheightnumbernullableurlstringnullablethumbnailUrlstringnullable
replyTostringnullablereactionsobject[]Show 2 child fieldsHide child fields
emojistringactorsstring[]
createdAtstringeditedAtstringnullabledeletedAtstringnullableversioninteger
mutedbooleanblockedstring[]canSendbooleanunreadCountintegercreatedAtstringupdatedAtstringversioninteger
Posts
/v1/postsList creators' posts in organic programs
const { data } = await lucra.posts.list({
query: { program: "prog_…" },
})Query parameters
programprog_…creatorcrtr_…platformenuminstagramtiktokstatusstringDefaults to every status but archived.
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 26 fields each, and nextCursorShow
idpost_…submissionsub_…creatorcrtr_…programprog_…connectionconn_…nullabletitlestringcreatorNamestringhandlestringplatformenuminstagramtiktokprogramNamestringproductprod_…nullableurlstringnullablevideoUrlstringnullablethumbnailUrlstringnullablestatusenumtracking (views being measured), ready_for_review, approved (reviewed; its payment waits on approval), payment_approved, paid or rejected; archived once hidden from the brand's view.
trackingready_for_reviewapprovedpayment_approvedpaidrejectedarchivedconfidenceenumThe fraud check on the post's views.
looks_goodneeds_reviewnot_enough_datareasonstringamountintegerWhat the creator earns (net); an estimate while the post is tracking.
currencystringLowercase ISO 4217 code, e.g. usd.
eligibleViewsnumbernullabletagsobject[]Each tag with the color it was assigned with.
Show 2 child fieldsHide child fields
namestringcolorenumgreydark_greypurpletealgreenyelloworangepink
dailyobject[]Show 6 child fieldsHide child fields
datestringviewsnumberengagementsnumbernullablelikesnumbernullablecommentsnumbernullablesharesnumbernullable
evidenceanyOn GET /v1/posts/:id: the claim's measurement windows, hourly snapshots, risk reasons, review history and payout account status.
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/posts/:idGet a post with its claim evidence
const { data } = await lucra.posts.retrieve({
path: { id: "post_…" },
})Path parameters
idpost_…· required
Response20026 fieldsShow
idpost_…submissionsub_…creatorcrtr_…programprog_…connectionconn_…nullabletitlestringcreatorNamestringhandlestringplatformenuminstagramtiktokprogramNamestringproductprod_…nullableurlstringnullablevideoUrlstringnullablethumbnailUrlstringnullablestatusenumtracking (views being measured), ready_for_review, approved (reviewed; its payment waits on approval), payment_approved, paid or rejected; archived once hidden from the brand's view.
trackingready_for_reviewapprovedpayment_approvedpaidrejectedarchivedconfidenceenumThe fraud check on the post's views.
looks_goodneeds_reviewnot_enough_datareasonstringamountintegerWhat the creator earns (net); an estimate while the post is tracking.
currencystringLowercase ISO 4217 code, e.g. usd.
eligibleViewsnumbernullabletagsobject[]Each tag with the color it was assigned with.
Show 2 child fieldsHide child fields
namestringcolorenumgreydark_greypurpletealgreenyelloworangepink
dailyobject[]Show 6 child fieldsHide child fields
datestringviewsnumberengagementsnumbernullablelikesnumbernullablecommentsnumbernullablesharesnumbernullable
evidenceanyOn GET /v1/posts/:id: the claim's measurement windows, hourly snapshots, risk reasons, review history and payout account status.
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/posts/:idTag or archive a post
const { data } = await lucra.posts.update({
path: { id: "post_…" },
body: { version: 1000 },
})Path parameters
idpost_…· required
Body
versionintegertagobjectShow 2 child fieldsHide child fields
namestring· requiredcolorenum· requiredgreydark_greypurpletealgreenyelloworangepink
assignedbooleanWith tag: add (true) or remove (false) it.
statusstringHides the post from the brand's view.
archived
Response20026 fieldsShow
idpost_…submissionsub_…creatorcrtr_…programprog_…connectionconn_…nullabletitlestringcreatorNamestringhandlestringplatformenuminstagramtiktokprogramNamestringproductprod_…nullableurlstringnullablevideoUrlstringnullablethumbnailUrlstringnullablestatusenumtracking (views being measured), ready_for_review, approved (reviewed; its payment waits on approval), payment_approved, paid or rejected; archived once hidden from the brand's view.
trackingready_for_reviewapprovedpayment_approvedpaidrejectedarchivedconfidenceenumThe fraud check on the post's views.
looks_goodneeds_reviewnot_enough_datareasonstringamountintegerWhat the creator earns (net); an estimate while the post is tracking.
currencystringLowercase ISO 4217 code, e.g. usd.
eligibleViewsnumbernullabletagsobject[]Each tag with the color it was assigned with.
Show 2 child fieldsHide child fields
namestringcolorenumgreydark_greypurpletealgreenyelloworangepink
dailyobject[]Show 6 child fieldsHide child fields
datestringviewsnumberengagementsnumbernullablelikesnumbernullablecommentsnumbernullablesharesnumbernullable
evidenceanyOn GET /v1/posts/:id: the claim's measurement windows, hourly snapshots, risk reasons, review history and payout account status.
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Ad authorizations
/v1/ad-authorizationsList 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_…platformenummetatiktokstatusstringOne 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_…nullableaccountacct_…The brand that asks.
brandNamestringplatformenummetatiktokstatusenumrequested by the brand, granted by the creator, revoked by either; expired once
expiresAtpasses.requestedgrantedrevokedexpiredhandlestringnullableOn TikTok, the handle of the post's creator.
postobjectnullableOn TikTok, the post the brand wants to run.
Show 4 child fieldsHide child fields
urlstringnullablehandlestringnullablecaptionstringnullablethumbnailUrlstringnullableTikTok's poster image; it expires, so read the authorization again for a fresh one.
requestUrlstringnullableOn TikTok, a link the creator opens, without a Lucra account, to send their Spark code.
authorizedAtstringnullableexpiresAtstringnullableWhen the creator's authorization (on TikTok, their Spark code) ends.
revokedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/ad-authorizations/:idGet an ad authorization
const { data } = await lucra.adAuthorizations.retrieve({
path: { id: "adauth_…" },
})Path parameters
idadauth_…· required
Response20016 fieldsShow
idadauth_…submissionsub_…creatorcrtr_…nullableaccountacct_…The brand that asks.
brandNamestringplatformenummetatiktokstatusenumrequested by the brand, granted by the creator, revoked by either; expired once
expiresAtpasses.requestedgrantedrevokedexpiredhandlestringnullableOn TikTok, the handle of the post's creator.
postobjectnullableOn TikTok, the post the brand wants to run.
Show 4 child fieldsHide child fields
urlstringnullablehandlestringnullablecaptionstringnullablethumbnailUrlstringnullableTikTok's poster image; it expires, so read the authorization again for a fresh one.
requestUrlstringnullableOn TikTok, a link the creator opens, without a Lucra account, to send their Spark code.
authorizedAtstringnullableexpiresAtstringnullableWhen the creator's authorization (on TikTok, their Spark code) ends.
revokedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/ad-authorizationsAsk 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_…· requiredAn approved submission of a creator, or on TikTok an existing post in your library.
platformenum· requiredmetatiktok
Response20116 fieldsShow
idadauth_…submissionsub_…creatorcrtr_…nullableaccountacct_…The brand that asks.
brandNamestringplatformenummetatiktokstatusenumrequested by the brand, granted by the creator, revoked by either; expired once
expiresAtpasses.requestedgrantedrevokedexpiredhandlestringnullableOn TikTok, the handle of the post's creator.
postobjectnullableOn TikTok, the post the brand wants to run.
Show 4 child fieldsHide child fields
urlstringnullablehandlestringnullablecaptionstringnullablethumbnailUrlstringnullableTikTok's poster image; it expires, so read the authorization again for a fresh one.
requestUrlstringnullableOn TikTok, a link the creator opens, without a Lucra account, to send their Spark code.
authorizedAtstringnullableexpiresAtstringnullableWhen the creator's authorization (on TikTok, their Spark code) ends.
revokedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/ad-authorizations/:idGrant 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· requiredgrantedrevokedsparkCodestringOn 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.
expiresAtstringOn Meta, with granted: when the creator's authorization ends, as they set it on the platform.
versioninteger
Response20016 fieldsShow
idadauth_…submissionsub_…creatorcrtr_…nullableaccountacct_…The brand that asks.
brandNamestringplatformenummetatiktokstatusenumrequested by the brand, granted by the creator, revoked by either; expired once
expiresAtpasses.requestedgrantedrevokedexpiredhandlestringnullableOn TikTok, the handle of the post's creator.
postobjectnullableOn TikTok, the post the brand wants to run.
Show 4 child fieldsHide child fields
urlstringnullablehandlestringnullablecaptionstringnullablethumbnailUrlstringnullableTikTok's poster image; it expires, so read the authorization again for a fresh one.
requestUrlstringnullableOn TikTok, a link the creator opens, without a Lucra account, to send their Spark code.
authorizedAtstringnullableexpiresAtstringnullableWhen the creator's authorization (on TikTok, their Spark code) ends.
revokedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Pixels
/v1/pixelsCreate a pixel
const { data } = await lucra.pixels.create({
body: { name: "…", domains: ["…"] },
})Body
namestring· requireddomainsstring[]· requiredOrigins the pixel may send from, like
https://shop.example.com.excludedCountriesstring[]Countries (ISO 3166-1 alpha-2) whose visitors the pixel doesn't record, decided by the visitor's IP country.
Response20112 fieldsShow
idpxl_…namestringdomainsstring[]excludedCountriesstring[]statusenumverified once the first event arrives from an allowed domain; archived pixels accept no events.
waitingverifiedarchivedlastSeenAtstringnullablesnippetstringPaste before </head> on every page of the allowed domains.
firstPartyobjectRecommended: proxy
pathon your site totarget(a rewrite in Next.js, Vercel, Cloudflare or nginx) and use this snippet instead. The pixel then keeps visitors' attribution in a first-party cookie, so Safari doesn't forget them after 7 days.Show 3 child fieldsHide child fields
pathstringtargetstringsnippetstring
qualityobjectOf the last 7 days' events: how many had consent, came from your server, carried user data or ad click IDs, were credited to a creator, and have a location.
Show 7 child fieldsHide child fields
eventsintegerconsentedintegerfromServerintegerwithUserDataintegerwithClickIdsintegercreditedintegerlocatedinteger
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/pixels/:id/eventsSend a conversion from the brand's server; 202 once it's recorded for attribution
const { data } = await lucra.pixels.events.create({
path: { id: "pxl_…" },
body: { name: "…" },
})Path parameters
idpxl_…· required
Body
namestring· requiredA standard event (page_view, view_content, search, add_to_cart, begin_checkout, purchase, lead, sign_up, start_trial, subscribe, contact) or your own, in snake_case.
occurredAtstringDefaults to now; must be within the last 7 days.
orderIdstringvalueintegerIn cents, with its currency.
currencystringISO 4217, in either case (
usdorUSD).consentenumRecorded by default, like the browser pixel; send
deniedorunknownwhen the visitor declined, and leave out lucraId, campaign, attributionId and clickId.granteddeniedunknownlucraIdstringlucra_idfrom the landing URL: the video (submission) the visitor came from.campaignstringlucra_campaignfrom the landing URL: the paid campaign (camp_…) whose ad the visitor came from.attributionIdstringlucra_attribution_idfrom older landing URLs; sendlucraIdfor new ones.clickIdstringeventIdstringSend the browser event's ID to count a conversion once when both fire.
pageUrlstringThe page the conversion happened on; defaults to the pixel's first domain.
propertiesobjectShow 5 child fieldsHide child fields
productIdstringquantityintegervariantIdstringcontentsobject[]Show 3 child fieldsHide child fields
idstring· requiredquantityintegerpriceintegerPer item, in cents, in the event's currency.
customobject
actionSourceenumWhere the conversion happened.
websiteappphysical_storephone_callchatemailsystem_generatedotherlandedAtstringWhen the visitor arrived from the video (
lucra_id), for conversion attribution windows.userobjectFor matching on ad platforms: hashed (SHA-256) on arrival, never stored raw; already-hashed values are kept.
Show 9 child fieldsHide child fields
emailstringphonestringfirstNamestringlastNamestringcitystringstatestringzipstringcountrystringexternalIdstring
clickIdsobjectAd click IDs and platform cookies from the visitor's browser.
Show 9 child fieldsHide child fields
fbcstringfbpstringgclidstringgbraidstringwbraidstringttclidstringttpstringsccidstringscidstring
ipAddressstringThe visitor's IP address; kept 13 months.
userAgentstringThe visitor's browser user agent, for their device and in-app browser.
creatorCodestringThe creator's code from the landing URL (
?lucra=CODE).discountCodestringThe order's discount code, recorded with the event.
locationobjectWhere the customer is, like the order's shipping address.
Show 4 child fieldsHide child fields
countrystringregionstringcitystringpostalCodestring
/v1/pixelsList pixels
const { data } = await lucra.pixels.list()Query parameters
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 12 fields each, and nextCursorShow
idpxl_…namestringdomainsstring[]excludedCountriesstring[]statusenumverified once the first event arrives from an allowed domain; archived pixels accept no events.
waitingverifiedarchivedlastSeenAtstringnullablesnippetstringPaste before </head> on every page of the allowed domains.
firstPartyobjectRecommended: proxy
pathon your site totarget(a rewrite in Next.js, Vercel, Cloudflare or nginx) and use this snippet instead. The pixel then keeps visitors' attribution in a first-party cookie, so Safari doesn't forget them after 7 days.Show 3 child fieldsHide child fields
pathstringtargetstringsnippetstring
qualityobjectOf the last 7 days' events: how many had consent, came from your server, carried user data or ad click IDs, were credited to a creator, and have a location.
Show 7 child fieldsHide child fields
eventsintegerconsentedintegerfromServerintegerwithUserDataintegerwithClickIdsintegercreditedintegerlocatedinteger
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/pixels/:idGet a pixel and whether it's verified
const { data } = await lucra.pixels.retrieve({
path: { id: "pxl_…" },
})Path parameters
idpxl_…· required
Response20012 fieldsShow
idpxl_…namestringdomainsstring[]excludedCountriesstring[]statusenumverified once the first event arrives from an allowed domain; archived pixels accept no events.
waitingverifiedarchivedlastSeenAtstringnullablesnippetstringPaste before </head> on every page of the allowed domains.
firstPartyobjectRecommended: proxy
pathon your site totarget(a rewrite in Next.js, Vercel, Cloudflare or nginx) and use this snippet instead. The pixel then keeps visitors' attribution in a first-party cookie, so Safari doesn't forget them after 7 days.Show 3 child fieldsHide child fields
pathstringtargetstringsnippetstring
qualityobjectOf the last 7 days' events: how many had consent, came from your server, carried user data or ad click IDs, were credited to a creator, and have a location.
Show 7 child fieldsHide child fields
eventsintegerconsentedintegerfromServerintegerwithUserDataintegerwithClickIdsintegercreditedintegerlocatedinteger
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/pixels/:idRename a pixel, change its domains or excluded countries, or archive it
const { data } = await lucra.pixels.update({
path: { id: "pxl_…" },
body: { name: "…" },
})Path parameters
idpxl_…· required
Body
namestringdomainsstring[]Origins the pixel may send from, like
https://shop.example.com.excludedCountriesstring[]Countries (ISO 3166-1 alpha-2) whose visitors the pixel doesn't record, decided by the visitor's IP country.
statusstringStops the pixel accepting events; its history stays.
archivedversioninteger
Response20012 fieldsShow
idpxl_…namestringdomainsstring[]excludedCountriesstring[]statusenumverified once the first event arrives from an allowed domain; archived pixels accept no events.
waitingverifiedarchivedlastSeenAtstringnullablesnippetstringPaste before </head> on every page of the allowed domains.
firstPartyobjectRecommended: proxy
pathon your site totarget(a rewrite in Next.js, Vercel, Cloudflare or nginx) and use this snippet instead. The pixel then keeps visitors' attribution in a first-party cookie, so Safari doesn't forget them after 7 days.Show 3 child fieldsHide child fields
pathstringtargetstringsnippetstring
qualityobjectOf the last 7 days' events: how many had consent, came from your server, carried user data or ad click IDs, were credited to a creator, and have a location.
Show 7 child fieldsHide child fields
eventsintegerconsentedintegerfromServerintegerwithUserDataintegerwithClickIdsintegercreditedintegerlocatedinteger
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Conversions
/v1/conversionsCreate a conversion: the events that count as a sign-up, a purchase or your own goal
const { data } = await lucra.conversions.create({
body: { name: "…", eventName: "…" },
})Body
namestring· requiredeventNamestring· requiredThe event that counts: a standard one (purchase, sign_up, lead…) or your own.
pageUrlContainsstringnullableOnly events on pages whose URL contains this (case-insensitive).
minValueobjectOnly events in this currency with at least this value count.
Show 2 child fieldsHide child fields
amountinteger· requiredIn cents.
currencystring· requiredISO 4217, in either case.
attributionWindowDaysintegerCredits the video when the visitor converts within this many days of landing from it.
payBrowserEventsbooleanPay creators on events only the browser sent. Anyone with your pixel ID can forge those, so by default only events your server or Shopify confirmed pay.
/v1/conversionsList conversions, newest first
const { data } = await lucra.conversions.list()Query parameters
Plus paging: limit, cursor, createdAfter and createdBefore.
/v1/conversions/:idGet a conversion and how many events counted as it
const { data } = await lucra.conversions.retrieve({
path: { id: "…" },
})Path parameters
idstring· required
/v1/conversions/:idChange a conversion or archive it; events already recorded keep counting as they did
const { data } = await lucra.conversions.update({
path: { id: "…" },
body: { name: "…" },
})Path parameters
idstring· required
Body
namestringeventNamestringThe event that counts: a standard one (purchase, sign_up, lead…) or your own.
pageUrlContainsstringnullableOnly events on pages whose URL contains this (case-insensitive).
minValueobjectnullableShow 2 child fieldsHide child fields
amountinteger· requiredIn cents.
currencystring· requiredISO 4217, in either case.
attributionWindowDaysintegerCredits the video when the visitor converts within this many days of landing from it.
payBrowserEventsbooleanPay creators on events only the browser sent. Anyone with your pixel ID can forge those, so by default only events your server or Shopify confirmed pay.
statusenumactivearchivedversioninteger
/v1/conversions/:id/reportBreak a conversion down by creator, place, in-app browser, source or day, with counts and value
const { data } = await lucra.conversions.report.retrieve({
path: { id: "…" },
query: { groupBy: "…" },
})Path parameters
idstring· required
Query parameters
groupBystring· requiredUp to 3, comma-separated: creator, country, region, city, inApp, deviceType, source, day.
fromstringOnly conversions at or after this time.
tostringOnly conversions before this time.
creditedenumtrue: only conversions credited to a creator.
truefalse
Response2001 fieldsShow
dataany[]
Pixel events
/v1/pixel-eventsList the events your pixels received, newest first
const { data } = await lucra.pixelEvents.list({
query: { pixel: "pxl_…" },
})Query parameters
pixelpxl_…conversionconv_…attributedenumtrue: only events credited to a creator (their video or their code).
truefalse
Plus paging: limit, cursor, createdAfter and createdBefore.
/v1/pixel-events/:idGet one pixel event, with what ad platforms' conversion APIs take
const { data } = await lucra.pixelEvents.retrieve({
path: { id: "…" },
})Path parameters
idstring· required
Embeds
/v1/embedsOpen Lucra UI for a brand or creator, hosted or embedded
const { data } = await lucra.embeds.create({
body: { components: ["onboarding"] },
})Body
componentsenum[]· requiredWhat the embed can show. programs, payments and ads are for brands; creator_programs and wallet are for creators; onboarding and messages are for either.
onboardingcreator_programswalletprogramspaymentsadsmessagesopenenumThe component the hosted url opens; defaults to the first in components.
onboardingcreator_programswalletprogramspaymentsadsmessagesproviderenumWith onboarding: the platform its connections step lists first.
metatiktokgooglesnapchatshopifyinstagramemailstringPrefill; defaults to the account's contact details.
phonestringreturnUrlstringWhere the hosted page sends the person when they finish.
appearanceobjectShow 3 child fieldsHide child fields
themeenumlightdarkautocolorsobjectShow 1 child fieldHide child fields
primarystring· required
radiusintegerCorner radius in px.
Response2019 fieldsShow
idemb_…accountstringThe brand (acct_…) or creator (crtr_…) it shows.
componentsenum[]onboardingcreator_programswalletprogramspaymentsadsmessagesstatusenumexpired once expiresAt passes, or when you end it with PATCH.
activeexpiredexpiresAtstringWhen url and any mounted components stop working.
createdAtstringurlstringThe hosted page; send the person here. Lasts 24 hours.
clientSecretstringPass to @lucra/sdk/embed in your frontend. Single use, from an allowed origin.
clientSecretExpiresAtstringMount the components before this; about 10 minutes.
/v1/embedsList the embeds you opened for a brand or creator
const { data } = await lucra.embeds.list()Query parameters
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 6 fields each, and nextCursorShow
idemb_…accountstringThe brand (acct_…) or creator (crtr_…) it shows.
componentsenum[]onboardingcreator_programswalletprogramspaymentsadsmessagesstatusenumexpired once expiresAt passes, or when you end it with PATCH.
activeexpiredexpiresAtstringWhen url and any mounted components stop working.
createdAtstring
/v1/embeds/:idGet an embed
const { data } = await lucra.embeds.retrieve({
path: { id: "emb_…" },
})Path parameters
idemb_…· required
Response2006 fieldsShow
idemb_…accountstringThe brand (acct_…) or creator (crtr_…) it shows.
componentsenum[]onboardingcreator_programswalletprogramspaymentsadsmessagesstatusenumexpired once expiresAt passes, or when you end it with PATCH.
activeexpiredexpiresAtstringWhen url and any mounted components stop working.
createdAtstring
/v1/embeds/:idEnd an embed early
const { data } = await lucra.embeds.update({
path: { id: "emb_…" },
body: { status: "expired" },
})Path parameters
idemb_…· required
Body
statusstring· requiredEnds it now: the hosted url and mounted components stop working.
expired
Response2006 fieldsShow
idemb_…accountstringThe brand (acct_…) or creator (crtr_…) it shows.
componentsenum[]onboardingcreator_programswalletprogramspaymentsadsmessagesstatusenumexpired once expiresAt passes, or when you end it with PATCH.
activeexpiredexpiresAtstringWhen url and any mounted components stop working.
createdAtstring
Products
/v1/productsList products; as a creator, the ones attached to the programs you're approved in, which you can ask a sample of
const { data } = await lucra.products.list()Query parameters
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 20 fields each, and nextCursorShow
idprod_…accountacct_…The brand whose catalog it's in.
brandNamestringnamestringvendorstringnullableproductTypestringnullabledescriptionstringnullableskustringnullablestatusstringnullableactive or archived; Shopify products can also be draft or unlisted.
urlstringnullableimageUrlstringnullableimagefile_…nullablesampleEligiblebooleanaccessCodestringnullableA masked summary of the code creators get instead of an order.
variantsobject[]Show 6 child fieldsHide child fields
idstringThe variant's ID in its store, as samples take it.
titlestringoptionstringnullablepriceintegernullableskustringnullableimageUrlstringnullable
currencystringnullableThe currency of variant prices; null for manual products.
externalobjectnullableThe store the product syncs from; null for products added in Lucra.
Show 3 child fieldsHide child fields
providerstringshopifyidstringurlstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/productsAdd a product to the catalog
const { data } = await lucra.products.create({
body: { name: "…" },
})Body
namestring· requiredproductTypestringurlstringdescriptionstringskustringimagefile_…sampleEligiblebooleanaccessCodestringstatusenumactivearchived
Response20120 fieldsShow
idprod_…accountacct_…The brand whose catalog it's in.
brandNamestringnamestringvendorstringnullableproductTypestringnullabledescriptionstringnullableskustringnullablestatusstringnullableactive or archived; Shopify products can also be draft or unlisted.
urlstringnullableimageUrlstringnullableimagefile_…nullablesampleEligiblebooleanaccessCodestringnullableA masked summary of the code creators get instead of an order.
variantsobject[]Show 6 child fieldsHide child fields
idstringThe variant's ID in its store, as samples take it.
titlestringoptionstringnullablepriceintegernullableskustringnullableimageUrlstringnullable
currencystringnullableThe currency of variant prices; null for manual products.
externalobjectnullableThe store the product syncs from; null for products added in Lucra.
Show 3 child fieldsHide child fields
providerstringshopifyidstringurlstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/products/:idGet a product
const { data } = await lucra.products.retrieve({
path: { id: "prod_…" },
})Path parameters
idprod_…· required
Response20020 fieldsShow
idprod_…accountacct_…The brand whose catalog it's in.
brandNamestringnamestringvendorstringnullableproductTypestringnullabledescriptionstringnullableskustringnullablestatusstringnullableactive or archived; Shopify products can also be draft or unlisted.
urlstringnullableimageUrlstringnullableimagefile_…nullablesampleEligiblebooleanaccessCodestringnullableA masked summary of the code creators get instead of an order.
variantsobject[]Show 6 child fieldsHide child fields
idstringThe variant's ID in its store, as samples take it.
titlestringoptionstringnullablepriceintegernullableskustringnullableimageUrlstringnullable
currencystringnullableThe currency of variant prices; null for manual products.
externalobjectnullableThe store the product syncs from; null for products added in Lucra.
Show 3 child fieldsHide child fields
providerstringshopifyidstringurlstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/products/:idEdit, archive or set the access code of a product
const { data } = await lucra.products.update({
path: { id: "prod_…" },
body: { version: 1000 },
})Path parameters
idprod_…· required
Body
versionintegernamestringproductTypestringurlstringnullabledescriptionstringnullableskustringnullableimagefile_…nullablesampleEligiblebooleanaccessCodestringnullablestatusenumactivearchived
Response20020 fieldsShow
idprod_…accountacct_…The brand whose catalog it's in.
brandNamestringnamestringvendorstringnullableproductTypestringnullabledescriptionstringnullableskustringnullablestatusstringnullableactive or archived; Shopify products can also be draft or unlisted.
urlstringnullableimageUrlstringnullableimagefile_…nullablesampleEligiblebooleanaccessCodestringnullableA masked summary of the code creators get instead of an order.
variantsobject[]Show 6 child fieldsHide child fields
idstringThe variant's ID in its store, as samples take it.
titlestringoptionstringnullablepriceintegernullableskustringnullableimageUrlstringnullable
currencystringnullableThe currency of variant prices; null for manual products.
externalobjectnullableThe store the product syncs from; null for products added in Lucra.
Show 3 child fieldsHide child fields
providerstringshopifyidstringurlstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Retainers
/v1/retainersList retainers
const { data } = await lucra.retainers.list({
query: { creator: "crtr_…" },
})Response200A page of items, 21 fields each, and nextCursorShow
idret_…creatorcrtr_…accountacct_…The brand that offers the retainer.
brandNamestringbrandAvatarUrlstringnullablekindenumsmart_retainer pays whichever is more each period: the guarantee (
pay.base) or the creator's program earnings from this account, up topay.cap.retainersmart_retainerdeliverableCountnumbernullableApproved deliverables expected each period.
payobjectShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
summarystringcurrencystringLowercase ISO 4217 code, e.g. usd.
statusenumdraftofferedacceptedactivecancelingendedrejectedbillingStatusstringcurrentPeriodEndAtstringnullabledeliverablesstringnullablenotesstringnullabledocumentsany[]The agreements accepting accepts;
acceptedonce the creator accepted that version with this brand.offeredAtstringacceptedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/retainers/:idGet a retainer
const { data } = await lucra.retainers.retrieve({
path: { id: "ret_…" },
})Path parameters
idret_…· required
Response20021 fieldsShow
idret_…creatorcrtr_…accountacct_…The brand that offers the retainer.
brandNamestringbrandAvatarUrlstringnullablekindenumsmart_retainer pays whichever is more each period: the guarantee (
pay.base) or the creator's program earnings from this account, up topay.cap.retainersmart_retainerdeliverableCountnumbernullableApproved deliverables expected each period.
payobjectShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
summarystringcurrencystringLowercase ISO 4217 code, e.g. usd.
statusenumdraftofferedacceptedactivecancelingendedrejectedbillingStatusstringcurrentPeriodEndAtstringnullabledeliverablesstringnullablenotesstringnullabledocumentsany[]The agreements accepting accepts;
acceptedonce the creator accepted that version with this brand.offeredAtstringacceptedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/retainersOffer a creator a retainer
const { data } = await lucra.retainers.create({
body: { creator: "crtr_…", pay: {} },
})Headers
Idempotency-Keystring· requiredUnique to this write; resend it to retry safely.
Body
creatorcrtr_…· requiredpayobject· requiredShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobject· requiredapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
kindenumsmart_retainer pays whichever is more each period:
pay.base(the guarantee) or the creator's program earnings from this account, up topay.cap; it has no rules.retainersmart_retainerdeliverableCountintegerApproved deliverables expected each period.
deliverablesstringnotesstring
Response20121 fieldsShow
idret_…creatorcrtr_…accountacct_…The brand that offers the retainer.
brandNamestringbrandAvatarUrlstringnullablekindenumsmart_retainer pays whichever is more each period: the guarantee (
pay.base) or the creator's program earnings from this account, up topay.cap.retainersmart_retainerdeliverableCountnumbernullableApproved deliverables expected each period.
payobjectShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
summarystringcurrencystringLowercase ISO 4217 code, e.g. usd.
statusenumdraftofferedacceptedactivecancelingendedrejectedbillingStatusstringcurrentPeriodEndAtstringnullabledeliverablesstringnullablenotesstringnullabledocumentsany[]The agreements accepting accepts;
acceptedonce the creator accepted that version with this brand.offeredAtstringacceptedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/retainers/:idCancel a retainer, or, as the creator, accept or reject an offer or cancel
const { data } = await lucra.retainers.update({
path: { id: "ret_…" },
body: { status: "accepted" },
})Path parameters
idret_…· required
Body
statusenum· requiredacceptedrejectedcancelingversioninteger
Response20021 fieldsShow
idret_…creatorcrtr_…accountacct_…The brand that offers the retainer.
brandNamestringbrandAvatarUrlstringnullablekindenumsmart_retainer pays whichever is more each period: the guarantee (
pay.base) or the creator's program earnings from this account, up topay.cap.retainersmart_retainerdeliverableCountnumbernullableApproved deliverables expected each period.
payobjectShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
summarystringcurrencystringLowercase ISO 4217 code, e.g. usd.
statusenumdraftofferedacceptedactivecancelingendedrejectedbillingStatusstringcurrentPeriodEndAtstringnullabledeliverablesstringnullablenotesstringnullabledocumentsany[]The agreements accepting accepts;
acceptedonce the creator accepted that version with this brand.offeredAtstringacceptedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Programs
/v1/programsList programs: your own (archived ones only with status=archived), or with scope=network the open programs on the Lucra Network
const { data } = await lucra.programs.list({
query: { scope: "network" },
})Query parameters
scopestringThe Lucra Network's open programs instead of your own.
networkvisibilityenuminvitenetworkstatusenumdraftopenpausedclosedarchived
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 37 fields each, and nextCursorShow
idprog_…accountacct_…The brand that runs the program.
brandNamestringThe brand's display name. Network programs are seen by creators who can't read the brand's account.
brandAvatarUrlstringnullableA short-lived link to the brand's picture.
joinedCreatorCountintegerCreators approved to the program.
joinedCreatorsobject[]A preview of up to four live, joined creators. Only public profile names and pictures.
Show 4 child fieldsHide child fields
idcrtr_…namestringinitialsstringavatarUrlstringnullable
namestringtypeenumorganicpaid_adsstatusenumdraftopenpausedclosedarchivedvisibilityenuminvite: creators the brand invites; network: any creator can find it and apply.
invitenetworkbriefstringnullableWhat creators read before applying.
platformsenum[]instagramtiktokpaidSocialPlatformsenum[]instagramtiktokallowManualOrganicUploadbooleanallowPaidPromotionbooleanallowPaidSocialUploadsbooleanrequireAdAuthorizationbooleanCreators grant an ad authorization (a Meta partnership; on TikTok, their account approved to your Business Center) before their work runs as a creator-identity ad.
submissionLimitsobjectShow 4 child fieldsHide child fields
modeenumlimitedunlimitedmaxnumberconcurrentModeenumlimitedunlimitedconcurrentMaxnumber
payobjectWhat creators earn. A creator reading the program sees their own pay, with any terms the brand set for them.
Show 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
paySummarystringThe pay in plain English, ready to show.
payVersionintegerThe pay's version, bumped by each pay edit. Admitted creators move to it on their next action in the program; each application shows the version it's on.
payIssuesobject[]Ways the program's pay can't be paid as set, for the brand to fix; it keeps paying as it does until then. Empty when there are none, and on programs seen on the network.
Show 3 child fieldsHide child fields
codeenumpay_invalid_valuepay_cap_zeropay_cap_below_amountpay_cap_requiredpay_base_needs_periodpay_schedule_mismatchpay_duplicate_rulepay_scope_invalidpay_exceeds_budgetpay_primary_missingpay_primary_changedpay_program_unsupportedpathstringmessagestring
promotedobjectShow 4 child fieldsHide child fields
typeenumnullableappofferotherproductsitenamestringnullableurlstringnullableproductsprod_…[]Catalog products, first one primary.
briefFilesobject[]Show 6 child fieldsHide child fields
filefile_…fileNamestringcontentTypestringsizenumberurlstringnullablepreviewobjectnullableShow 3 child fieldsHide child fields
urlstringcontentTypestringnullablesizenumbernullable
referenceVideosobject[]Show 7 child fieldsHide child fields
filefile_…fileNamestringcontentTypestringsizenumberurlstringnullablewidthnumbernullableheightnumbernullable
agreementsany[]The agreements applying accepts: each one's current version.
submissionAgreementsany[]The agreements submitting work to the program accepts.
currencystringLowercase ISO 4217 code, e.g. usd.
budgetobjectnullableThe brand's own numbers; null on programs seen on the network.
Show 1 child fieldHide child fields
amountnumbernullableThe planned budget.
adSpendobjectnullableShow 2 child fieldsHide child fields
totalnumberbyPlatformobject[]Show 2 child fieldsHide child fields
platformstringamountnumber
partnerApprovalobjectnullableShow 3 child fieldsHide child fields
statusenumdraftpendingapprovedrejectedchanges_requestedlaunchednotestringnullablerequestedAtstringnullable
createdByPartneracct_…nullablestartsAtstringnullableendsAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/programs/:idGet a program
const { data } = await lucra.programs.retrieve({
path: { id: "prog_…" },
})Path parameters
idprog_…· required
Response20037 fieldsShow
idprog_…accountacct_…The brand that runs the program.
brandNamestringThe brand's display name. Network programs are seen by creators who can't read the brand's account.
brandAvatarUrlstringnullableA short-lived link to the brand's picture.
joinedCreatorCountintegerCreators approved to the program.
joinedCreatorsobject[]A preview of up to four live, joined creators. Only public profile names and pictures.
Show 4 child fieldsHide child fields
idcrtr_…namestringinitialsstringavatarUrlstringnullable
namestringtypeenumorganicpaid_adsstatusenumdraftopenpausedclosedarchivedvisibilityenuminvite: creators the brand invites; network: any creator can find it and apply.
invitenetworkbriefstringnullableWhat creators read before applying.
platformsenum[]instagramtiktokpaidSocialPlatformsenum[]instagramtiktokallowManualOrganicUploadbooleanallowPaidPromotionbooleanallowPaidSocialUploadsbooleanrequireAdAuthorizationbooleanCreators grant an ad authorization (a Meta partnership; on TikTok, their account approved to your Business Center) before their work runs as a creator-identity ad.
submissionLimitsobjectShow 4 child fieldsHide child fields
modeenumlimitedunlimitedmaxnumberconcurrentModeenumlimitedunlimitedconcurrentMaxnumber
payobjectWhat creators earn. A creator reading the program sees their own pay, with any terms the brand set for them.
Show 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
paySummarystringThe pay in plain English, ready to show.
payVersionintegerThe pay's version, bumped by each pay edit. Admitted creators move to it on their next action in the program; each application shows the version it's on.
payIssuesobject[]Ways the program's pay can't be paid as set, for the brand to fix; it keeps paying as it does until then. Empty when there are none, and on programs seen on the network.
Show 3 child fieldsHide child fields
codeenumpay_invalid_valuepay_cap_zeropay_cap_below_amountpay_cap_requiredpay_base_needs_periodpay_schedule_mismatchpay_duplicate_rulepay_scope_invalidpay_exceeds_budgetpay_primary_missingpay_primary_changedpay_program_unsupportedpathstringmessagestring
promotedobjectShow 4 child fieldsHide child fields
typeenumnullableappofferotherproductsitenamestringnullableurlstringnullableproductsprod_…[]Catalog products, first one primary.
briefFilesobject[]Show 6 child fieldsHide child fields
filefile_…fileNamestringcontentTypestringsizenumberurlstringnullablepreviewobjectnullableShow 3 child fieldsHide child fields
urlstringcontentTypestringnullablesizenumbernullable
referenceVideosobject[]Show 7 child fieldsHide child fields
filefile_…fileNamestringcontentTypestringsizenumberurlstringnullablewidthnumbernullableheightnumbernullable
agreementsany[]The agreements applying accepts: each one's current version.
submissionAgreementsany[]The agreements submitting work to the program accepts.
currencystringLowercase ISO 4217 code, e.g. usd.
budgetobjectnullableThe brand's own numbers; null on programs seen on the network.
Show 1 child fieldHide child fields
amountnumbernullableThe planned budget.
adSpendobjectnullableShow 2 child fieldsHide child fields
totalnumberbyPlatformobject[]Show 2 child fieldsHide child fields
platformstringamountnumber
partnerApprovalobjectnullableShow 3 child fieldsHide child fields
statusenumdraftpendingapprovedrejectedchanges_requestedlaunchednotestringnullablerequestedAtstringnullable
createdByPartneracct_…nullablestartsAtstringnullableendsAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/programsCreate a program
const { data } = await lucra.programs.create({
body: { name: "…", type: "organic", visibility: "invite" },
})Body
namestring· requiredtypeenum· requiredorganicpaid_adsvisibilityenum· requiredinvitenetworkbriefstringplatformsenum[]instagramtiktokpaidSocialPlatformsenum[]instagramtiktokallowManualOrganicUploadbooleanallowPaidPromotionbooleanallowPaidSocialUploadsbooleanrequireAdAuthorizationbooleansubmissionLimitsobjectShow 4 child fieldsHide child fields
modeenumlimitedunlimitedmaxintegerconcurrentModeenumlimitedunlimitedconcurrentMaxinteger
payobject· requiredShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobject· requiredapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
promotedobjectShow 4 child fieldsHide child fields
typeenumappofferotherproductsitenamestringurlstringproductsprod_…[]
budgetobjectShow 1 child fieldHide child fields
amountinteger
briefFilesfile_…[]referenceVideosfile_…[]agreementsagr_…[]
Response20137 fieldsShow
idprog_…accountacct_…The brand that runs the program.
brandNamestringThe brand's display name. Network programs are seen by creators who can't read the brand's account.
brandAvatarUrlstringnullableA short-lived link to the brand's picture.
joinedCreatorCountintegerCreators approved to the program.
joinedCreatorsobject[]A preview of up to four live, joined creators. Only public profile names and pictures.
Show 4 child fieldsHide child fields
idcrtr_…namestringinitialsstringavatarUrlstringnullable
namestringtypeenumorganicpaid_adsstatusenumdraftopenpausedclosedarchivedvisibilityenuminvite: creators the brand invites; network: any creator can find it and apply.
invitenetworkbriefstringnullableWhat creators read before applying.
platformsenum[]instagramtiktokpaidSocialPlatformsenum[]instagramtiktokallowManualOrganicUploadbooleanallowPaidPromotionbooleanallowPaidSocialUploadsbooleanrequireAdAuthorizationbooleanCreators grant an ad authorization (a Meta partnership; on TikTok, their account approved to your Business Center) before their work runs as a creator-identity ad.
submissionLimitsobjectShow 4 child fieldsHide child fields
modeenumlimitedunlimitedmaxnumberconcurrentModeenumlimitedunlimitedconcurrentMaxnumber
payobjectWhat creators earn. A creator reading the program sees their own pay, with any terms the brand set for them.
Show 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
paySummarystringThe pay in plain English, ready to show.
payVersionintegerThe pay's version, bumped by each pay edit. Admitted creators move to it on their next action in the program; each application shows the version it's on.
payIssuesobject[]Ways the program's pay can't be paid as set, for the brand to fix; it keeps paying as it does until then. Empty when there are none, and on programs seen on the network.
Show 3 child fieldsHide child fields
codeenumpay_invalid_valuepay_cap_zeropay_cap_below_amountpay_cap_requiredpay_base_needs_periodpay_schedule_mismatchpay_duplicate_rulepay_scope_invalidpay_exceeds_budgetpay_primary_missingpay_primary_changedpay_program_unsupportedpathstringmessagestring
promotedobjectShow 4 child fieldsHide child fields
typeenumnullableappofferotherproductsitenamestringnullableurlstringnullableproductsprod_…[]Catalog products, first one primary.
briefFilesobject[]Show 6 child fieldsHide child fields
filefile_…fileNamestringcontentTypestringsizenumberurlstringnullablepreviewobjectnullableShow 3 child fieldsHide child fields
urlstringcontentTypestringnullablesizenumbernullable
referenceVideosobject[]Show 7 child fieldsHide child fields
filefile_…fileNamestringcontentTypestringsizenumberurlstringnullablewidthnumbernullableheightnumbernullable
agreementsany[]The agreements applying accepts: each one's current version.
submissionAgreementsany[]The agreements submitting work to the program accepts.
currencystringLowercase ISO 4217 code, e.g. usd.
budgetobjectnullableThe brand's own numbers; null on programs seen on the network.
Show 1 child fieldHide child fields
amountnumbernullableThe planned budget.
adSpendobjectnullableShow 2 child fieldsHide child fields
totalnumberbyPlatformobject[]Show 2 child fieldsHide child fields
platformstringamountnumber
partnerApprovalobjectnullableShow 3 child fieldsHide child fields
statusenumdraftpendingapprovedrejectedchanges_requestedlaunchednotestringnullablerequestedAtstringnullable
createdByPartneracct_…nullablestartsAtstringnullableendsAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/programs/:idUpdate a program; every change in one request applies together, or none does
const { data } = await lucra.programs.update({
path: { id: "prog_…" },
body: { name: "…" },
})Path parameters
idprog_…· required
Body
namestringbriefstringstatusenumdraftopenpausedarchivedvisibilityenuminvitenetworksubmissionLimitsobjectShow 4 child fieldsHide child fields
modeenumlimitedunlimitedmaxintegerconcurrentModeenumlimitedunlimitedconcurrentMaxinteger
promotedobjectReplaces the promoted catalog products, first one primary.
Show 1 child fieldHide child fields
productsprod_…[]· required
briefFilesfile_…[]referenceVideosfile_…[]agreementsagr_…[]payobjectShow 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobject· requiredapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
budgetobjectShow 1 child fieldHide child fields
amountinteger
versioninteger
Response20037 fieldsShow
idprog_…accountacct_…The brand that runs the program.
brandNamestringThe brand's display name. Network programs are seen by creators who can't read the brand's account.
brandAvatarUrlstringnullableA short-lived link to the brand's picture.
joinedCreatorCountintegerCreators approved to the program.
joinedCreatorsobject[]A preview of up to four live, joined creators. Only public profile names and pictures.
Show 4 child fieldsHide child fields
idcrtr_…namestringinitialsstringavatarUrlstringnullable
namestringtypeenumorganicpaid_adsstatusenumdraftopenpausedclosedarchivedvisibilityenuminvite: creators the brand invites; network: any creator can find it and apply.
invitenetworkbriefstringnullableWhat creators read before applying.
platformsenum[]instagramtiktokpaidSocialPlatformsenum[]instagramtiktokallowManualOrganicUploadbooleanallowPaidPromotionbooleanallowPaidSocialUploadsbooleanrequireAdAuthorizationbooleanCreators grant an ad authorization (a Meta partnership; on TikTok, their account approved to your Business Center) before their work runs as a creator-identity ad.
submissionLimitsobjectShow 4 child fieldsHide child fields
modeenumlimitedunlimitedmaxnumberconcurrentModeenumlimitedunlimitedconcurrentMaxnumber
payobjectWhat creators earn. A creator reading the program sees their own pay, with any terms the brand set for them.
Show 5 child fieldsHide child fields
rulesobject[]baseintegerGuaranteed each period, in cents.
capintegernullableThe most one creator is paid per period, in cents; null or left out for no cap.
scheduleobjectapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
paySummarystringThe pay in plain English, ready to show.
payVersionintegerThe pay's version, bumped by each pay edit. Admitted creators move to it on their next action in the program; each application shows the version it's on.
payIssuesobject[]Ways the program's pay can't be paid as set, for the brand to fix; it keeps paying as it does until then. Empty when there are none, and on programs seen on the network.
Show 3 child fieldsHide child fields
codeenumpay_invalid_valuepay_cap_zeropay_cap_below_amountpay_cap_requiredpay_base_needs_periodpay_schedule_mismatchpay_duplicate_rulepay_scope_invalidpay_exceeds_budgetpay_primary_missingpay_primary_changedpay_program_unsupportedpathstringmessagestring
promotedobjectShow 4 child fieldsHide child fields
typeenumnullableappofferotherproductsitenamestringnullableurlstringnullableproductsprod_…[]Catalog products, first one primary.
briefFilesobject[]Show 6 child fieldsHide child fields
filefile_…fileNamestringcontentTypestringsizenumberurlstringnullablepreviewobjectnullableShow 3 child fieldsHide child fields
urlstringcontentTypestringnullablesizenumbernullable
referenceVideosobject[]Show 7 child fieldsHide child fields
filefile_…fileNamestringcontentTypestringsizenumberurlstringnullablewidthnumbernullableheightnumbernullable
agreementsany[]The agreements applying accepts: each one's current version.
submissionAgreementsany[]The agreements submitting work to the program accepts.
currencystringLowercase ISO 4217 code, e.g. usd.
budgetobjectnullableThe brand's own numbers; null on programs seen on the network.
Show 1 child fieldHide child fields
amountnumbernullableThe planned budget.
adSpendobjectnullableShow 2 child fieldsHide child fields
totalnumberbyPlatformobject[]Show 2 child fieldsHide child fields
platformstringamountnumber
partnerApprovalobjectnullableShow 3 child fieldsHide child fields
statusenumdraftpendingapprovedrejectedchanges_requestedlaunchednotestringnullablerequestedAtstringnullable
createdByPartneracct_…nullablestartsAtstringnullableendsAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Samples
/v1/samplesList samples
const { data } = await lucra.samples.list({
query: { product: "prod_…" },
})Query parameters
productprod_…creatorcrtr_…statusstringOne or more, comma-separated: requested, approved, rejected, shipping, shipped, failed.
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 13 fields each, and nextCursorShow
idsmpl_…creatorcrtr_…nullableproductprod_…nullableproductNamestringThe product's name when the sample was made, so it reads even if the product isn't one you can see.
variantobjectnullableShow 2 child fieldsHide child fields
idstringnullableThe store's variant ID; null for products added in Lucra.
titlestring
statusenumrequested, then approved or rejected by the brand; shipping once an order or access code is being made, then shipped, or failed.
requestedapprovedrejectedshippingshippedfailedprogramprog_…nullablenotestringnullableThe creator's note with a request.
decidedAtstringnullableshipmentobjectnullableThe order or access code that went out.
Show 8 child fieldsHide child fields
statusenumThe store's own progress: pending, invoice_pending, order_created, access_code_ready or failed.
pendinginvoice_pendingorder_createdaccess_code_readyfailedmethodenumorderaccess_codequantitynumberfulfillmentStatusstringnullableaccessCodestringnullableMasked, unless the creator reads the sample with expand=accessCode.
errorstringnullableorderobjectnullableShow 4 child fieldsHide child fields
idstringnullablenamestringnullabledraftIdstringnullableshopDomainstring
trackingobjectnullableShow 3 child fieldsHide child fields
companystringnullablenumberstringurlstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/samplesRequest a sample as a creator, or send one to a creator as the brand
const { data } = await lucra.samples.create({
body: { },
})Response20113 fieldsShow
idsmpl_…creatorcrtr_…nullableproductprod_…nullableproductNamestringThe product's name when the sample was made, so it reads even if the product isn't one you can see.
variantobjectnullableShow 2 child fieldsHide child fields
idstringnullableThe store's variant ID; null for products added in Lucra.
titlestring
statusenumrequested, then approved or rejected by the brand; shipping once an order or access code is being made, then shipped, or failed.
requestedapprovedrejectedshippingshippedfailedprogramprog_…nullablenotestringnullableThe creator's note with a request.
decidedAtstringnullableshipmentobjectnullableThe order or access code that went out.
Show 8 child fieldsHide child fields
statusenumThe store's own progress: pending, invoice_pending, order_created, access_code_ready or failed.
pendinginvoice_pendingorder_createdaccess_code_readyfailedmethodenumorderaccess_codequantitynumberfulfillmentStatusstringnullableaccessCodestringnullableMasked, unless the creator reads the sample with expand=accessCode.
errorstringnullableorderobjectnullableShow 4 child fieldsHide child fields
idstringnullablenamestringnullabledraftIdstringnullableshopDomainstring
trackingobjectnullableShow 3 child fieldsHide child fields
companystringnullablenumberstringurlstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/samples/:idGet a sample; its creator can reveal an access code with expand=accessCode
const { data } = await lucra.samples.retrieve({
path: { id: "smpl_…" },
query: { expand: "accessCode" },
})Path parameters
idsmpl_…· required
Query parameters
expandstringAs the creator:
shipment.accessCodewhole instead of masked. Each reveal is logged.accessCode
Response20013 fieldsShow
idsmpl_…creatorcrtr_…nullableproductprod_…nullableproductNamestringThe product's name when the sample was made, so it reads even if the product isn't one you can see.
variantobjectnullableShow 2 child fieldsHide child fields
idstringnullableThe store's variant ID; null for products added in Lucra.
titlestring
statusenumrequested, then approved or rejected by the brand; shipping once an order or access code is being made, then shipped, or failed.
requestedapprovedrejectedshippingshippedfailedprogramprog_…nullablenotestringnullableThe creator's note with a request.
decidedAtstringnullableshipmentobjectnullableThe order or access code that went out.
Show 8 child fieldsHide child fields
statusenumThe store's own progress: pending, invoice_pending, order_created, access_code_ready or failed.
pendinginvoice_pendingorder_createdaccess_code_readyfailedmethodenumorderaccess_codequantitynumberfulfillmentStatusstringnullableaccessCodestringnullableMasked, unless the creator reads the sample with expand=accessCode.
errorstringnullableorderobjectnullableShow 4 child fieldsHide child fields
idstringnullablenamestringnullabledraftIdstringnullableshopDomainstring
trackingobjectnullableShow 3 child fieldsHide child fields
companystringnullablenumberstringurlstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/samples/:idApprove or reject a sample request
const { data } = await lucra.samples.update({
path: { id: "smpl_…" },
body: { status: "approved" },
})Path parameters
idsmpl_…· required
Body
statusenum· requiredapprovedrejectedversioninteger
Response20013 fieldsShow
idsmpl_…creatorcrtr_…nullableproductprod_…nullableproductNamestringThe product's name when the sample was made, so it reads even if the product isn't one you can see.
variantobjectnullableShow 2 child fieldsHide child fields
idstringnullableThe store's variant ID; null for products added in Lucra.
titlestring
statusenumrequested, then approved or rejected by the brand; shipping once an order or access code is being made, then shipped, or failed.
requestedapprovedrejectedshippingshippedfailedprogramprog_…nullablenotestringnullableThe creator's note with a request.
decidedAtstringnullableshipmentobjectnullableThe order or access code that went out.
Show 8 child fieldsHide child fields
statusenumThe store's own progress: pending, invoice_pending, order_created, access_code_ready or failed.
pendinginvoice_pendingorder_createdaccess_code_readyfailedmethodenumorderaccess_codequantitynumberfulfillmentStatusstringnullableaccessCodestringnullableMasked, unless the creator reads the sample with expand=accessCode.
errorstringnullableorderobjectnullableShow 4 child fieldsHide child fields
idstringnullablenamestringnullabledraftIdstringnullableshopDomainstring
trackingobjectnullableShow 3 child fieldsHide child fields
companystringnullablenumberstringurlstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Submissions
/v1/submissionsList submissions
const { data } = await lucra.submissions.list({
query: { program: "prog_…" },
})Query parameters
programprog_…creatorcrtr_…statusstringOne or more, comma-separated: pending, revision_requested, approved, live, rejected, measuring, withdrawn, archived.
Plus paging: limit, cursor, createdAfter and createdBefore.
Response200A page of items, 19 fields each, and nextCursorShow
idsub_…typeenumpost: the creator's published Instagram or TikTok post; video: an uploaded video.
videopostprogramprog_…nullablecreatorcrtr_…nullablerevisionOfsub_…nullablestatusenumA post measures its views first (measuring), then waits for review (pending). withdrawn: by the creator; archived: kept but hidden from lists unless
status=archivedis asked for.pendingrevision_requestedapprovedliverejectedmeasuringwithdrawnarchivedfeedbackstringnullableThe brand's note with its latest review, such as what to change in a revision.
shortIdstringnullableThe short ID shown in the app and ad names.
submittedAtstringnullabletagsstring[]mediaobjectnullableShow 6 child fieldsHide child fields
videoUrlstringnullablethumbnailUrlstringnullabledurationSecondsnumbernullablefileNamestringnullablesizenumbernullablecontentTypestringnullable
platformPostobjectnullableThe creator's published post this submission is, for a post.
Show 9 child fieldsHide child fields
idstringnullableThe post's ID on its platform.
platformenuminstagramtiktokurlstringnullablecaptionstringnullablemetricsobjectShow 5 child fieldsHide child fields
viewsnumbernullablelikesnumbernullablecommentsnumbernullablesharesnumbernullablesavesnumbernullable
publishedAtstringnullablepaidViewsnumbernullableViews counted toward pay once measurement ends.
measurementEndsAtstringnullablepaymentApprovedAtstringnullable
transcriptobjectnullableShow 3 child fieldsHide child fields
statusenumcompletedfailedpendingskippedunsupportedtextstringnullablesegmentsobject[]nullableThe transcript as timed lines,
startandendin seconds from the video's start.Show 3 child fieldsHide child fields
startnumberendnumbertextstring
adsobjectnullableShow 4 child fieldsHide child fields
identityenumnullablecreatorbrandlaunchedOnstring[]ownershipstringnullableprogramTypestringnullable
existingPostobjectA brand's existing TikTok post to boost (added with
post): no upload, it runs as itself. Absent for an uploaded video.Show 4 child fieldsHide child fields
connectionconn_…The TikTok ad connection it runs on.
handlestringnullablereadybooleanAuthorized to the advertiser, so campaigns can run it; false while waiting on the creator's Spark code, or once it expires.
authorizedUntilstringnullable
adAuthorizationobjectnullableThe newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
idadauth_…platformenummetatiktokstatusenumrequestedgrantedrevokedexpiredauthorizedAtstringnullableexpiresAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/submissions/:idGet a submission
const { data } = await lucra.submissions.retrieve({
path: { id: "sub_…" },
})Path parameters
idsub_…· required
Response20019 fieldsShow
idsub_…typeenumpost: the creator's published Instagram or TikTok post; video: an uploaded video.
videopostprogramprog_…nullablecreatorcrtr_…nullablerevisionOfsub_…nullablestatusenumA post measures its views first (measuring), then waits for review (pending). withdrawn: by the creator; archived: kept but hidden from lists unless
status=archivedis asked for.pendingrevision_requestedapprovedliverejectedmeasuringwithdrawnarchivedfeedbackstringnullableThe brand's note with its latest review, such as what to change in a revision.
shortIdstringnullableThe short ID shown in the app and ad names.
submittedAtstringnullabletagsstring[]mediaobjectnullableShow 6 child fieldsHide child fields
videoUrlstringnullablethumbnailUrlstringnullabledurationSecondsnumbernullablefileNamestringnullablesizenumbernullablecontentTypestringnullable
platformPostobjectnullableThe creator's published post this submission is, for a post.
Show 9 child fieldsHide child fields
idstringnullableThe post's ID on its platform.
platformenuminstagramtiktokurlstringnullablecaptionstringnullablemetricsobjectShow 5 child fieldsHide child fields
viewsnumbernullablelikesnumbernullablecommentsnumbernullablesharesnumbernullablesavesnumbernullable
publishedAtstringnullablepaidViewsnumbernullableViews counted toward pay once measurement ends.
measurementEndsAtstringnullablepaymentApprovedAtstringnullable
transcriptobjectnullableShow 3 child fieldsHide child fields
statusenumcompletedfailedpendingskippedunsupportedtextstringnullablesegmentsobject[]nullableThe transcript as timed lines,
startandendin seconds from the video's start.Show 3 child fieldsHide child fields
startnumberendnumbertextstring
adsobjectnullableShow 4 child fieldsHide child fields
identityenumnullablecreatorbrandlaunchedOnstring[]ownershipstringnullableprogramTypestringnullable
existingPostobjectA brand's existing TikTok post to boost (added with
post): no upload, it runs as itself. Absent for an uploaded video.Show 4 child fieldsHide child fields
connectionconn_…The TikTok ad connection it runs on.
handlestringnullablereadybooleanAuthorized to the advertiser, so campaigns can run it; false while waiting on the creator's Spark code, or once it expires.
authorizedUntilstringnullable
adAuthorizationobjectnullableThe newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
idadauth_…platformenummetatiktokstatusenumrequestedgrantedrevokedexpiredauthorizedAtstringnullableexpiresAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/submissionsSubmit work as a creator, or add a brand's own video, or an existing TikTok post to boost, to its library
const { data } = await lucra.submissions.create({
body: { program: "prog_…" },
})Body
programprog_…The program the work is for; required for a creator.
filefile_…The uploaded video; required unless
postis sent.notestringpostobjectAs a brand: an existing TikTok post to run as a Spark Ad, by its creator's Spark code, its link, or both.
Show 3 child fieldsHide child fields
connectionconn_…· requiredThe brand's TikTok ad connection that will run the post.
urlstringThe post's full link, like https://www.tiktok.com/@handle/video/7234…
sparkCodestringThe creator's Spark code for the post; without one, Lucra asks the creator.
postUrlstringThe URL of the creator's published Instagram or TikTok post this video is; organic programs pay on its views.
revisionOfsub_…attestationobjectThe creator's content-compliance confirmations.
Show 4 child fieldsHide child fields
disclosureIncludedboolean· requiredexperienceTruthfulboolean· requirednoUnapprovedClaimsboolean· requiredacceptedAgreementsobject[]The agreement versions the creator accepted by submitting; refused with 409 agreements_changed if the program now requires others.
Show 2 child fieldsHide child fields
agreementagr_…· requiredversioninteger· required
namestringA brand library video's title; defaults to its file name.
Response20119 fieldsShow
idsub_…typeenumpost: the creator's published Instagram or TikTok post; video: an uploaded video.
videopostprogramprog_…nullablecreatorcrtr_…nullablerevisionOfsub_…nullablestatusenumA post measures its views first (measuring), then waits for review (pending). withdrawn: by the creator; archived: kept but hidden from lists unless
status=archivedis asked for.pendingrevision_requestedapprovedliverejectedmeasuringwithdrawnarchivedfeedbackstringnullableThe brand's note with its latest review, such as what to change in a revision.
shortIdstringnullableThe short ID shown in the app and ad names.
submittedAtstringnullabletagsstring[]mediaobjectnullableShow 6 child fieldsHide child fields
videoUrlstringnullablethumbnailUrlstringnullabledurationSecondsnumbernullablefileNamestringnullablesizenumbernullablecontentTypestringnullable
platformPostobjectnullableThe creator's published post this submission is, for a post.
Show 9 child fieldsHide child fields
idstringnullableThe post's ID on its platform.
platformenuminstagramtiktokurlstringnullablecaptionstringnullablemetricsobjectShow 5 child fieldsHide child fields
viewsnumbernullablelikesnumbernullablecommentsnumbernullablesharesnumbernullablesavesnumbernullable
publishedAtstringnullablepaidViewsnumbernullableViews counted toward pay once measurement ends.
measurementEndsAtstringnullablepaymentApprovedAtstringnullable
transcriptobjectnullableShow 3 child fieldsHide child fields
statusenumcompletedfailedpendingskippedunsupportedtextstringnullablesegmentsobject[]nullableThe transcript as timed lines,
startandendin seconds from the video's start.Show 3 child fieldsHide child fields
startnumberendnumbertextstring
adsobjectnullableShow 4 child fieldsHide child fields
identityenumnullablecreatorbrandlaunchedOnstring[]ownershipstringnullableprogramTypestringnullable
existingPostobjectA brand's existing TikTok post to boost (added with
post): no upload, it runs as itself. Absent for an uploaded video.Show 4 child fieldsHide child fields
connectionconn_…The TikTok ad connection it runs on.
handlestringnullablereadybooleanAuthorized to the advertiser, so campaigns can run it; false while waiting on the creator's Spark code, or once it expires.
authorizedUntilstringnullable
adAuthorizationobjectnullableThe newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
idadauth_…platformenummetatiktokstatusenumrequestedgrantedrevokedexpiredauthorizedAtstringnullableexpiresAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/submissions/:idReview, tag, file or archive a submission, or approve paying for a post; as its creator, withdraw it
const { data } = await lucra.submissions.update({
path: { id: "sub_…" },
body: { status: "pending" },
})Path parameters
idsub_…· required
Body
statusenumA post in an organic program is approved (paid on its measured views) or rejected; archived hides a rejected or withdrawn submission from lists (it stays readable, and lists with
status=archived); a creator sends withdrawn. Any member may approve, reject or request a revision (with a note); other changes need an owner or admin.pendingapprovedrejectedrevision_requestedwithdrawnarchivednotestringShown to the creator with a revision request or rejection.
tagsstring[]paymentstringFor an approved post: approves paying the creator its finalized earnings (the brand's owner, admin or own key).
approvedversioninteger
Response20019 fieldsShow
idsub_…typeenumpost: the creator's published Instagram or TikTok post; video: an uploaded video.
videopostprogramprog_…nullablecreatorcrtr_…nullablerevisionOfsub_…nullablestatusenumA post measures its views first (measuring), then waits for review (pending). withdrawn: by the creator; archived: kept but hidden from lists unless
status=archivedis asked for.pendingrevision_requestedapprovedliverejectedmeasuringwithdrawnarchivedfeedbackstringnullableThe brand's note with its latest review, such as what to change in a revision.
shortIdstringnullableThe short ID shown in the app and ad names.
submittedAtstringnullabletagsstring[]mediaobjectnullableShow 6 child fieldsHide child fields
videoUrlstringnullablethumbnailUrlstringnullabledurationSecondsnumbernullablefileNamestringnullablesizenumbernullablecontentTypestringnullable
platformPostobjectnullableThe creator's published post this submission is, for a post.
Show 9 child fieldsHide child fields
idstringnullableThe post's ID on its platform.
platformenuminstagramtiktokurlstringnullablecaptionstringnullablemetricsobjectShow 5 child fieldsHide child fields
viewsnumbernullablelikesnumbernullablecommentsnumbernullablesharesnumbernullablesavesnumbernullable
publishedAtstringnullablepaidViewsnumbernullableViews counted toward pay once measurement ends.
measurementEndsAtstringnullablepaymentApprovedAtstringnullable
transcriptobjectnullableShow 3 child fieldsHide child fields
statusenumcompletedfailedpendingskippedunsupportedtextstringnullablesegmentsobject[]nullableThe transcript as timed lines,
startandendin seconds from the video's start.Show 3 child fieldsHide child fields
startnumberendnumbertextstring
adsobjectnullableShow 4 child fieldsHide child fields
identityenumnullablecreatorbrandlaunchedOnstring[]ownershipstringnullableprogramTypestringnullable
existingPostobjectA brand's existing TikTok post to boost (added with
post): no upload, it runs as itself. Absent for an uploaded video.Show 4 child fieldsHide child fields
connectionconn_…The TikTok ad connection it runs on.
handlestringnullablereadybooleanAuthorized to the advertiser, so campaigns can run it; false while waiting on the creator's Spark code, or once it expires.
authorizedUntilstringnullable
adAuthorizationobjectnullableThe newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
idadauth_…platformenummetatiktokstatusenumrequestedgrantedrevokedexpiredauthorizedAtstringnullableexpiresAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring