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
lucra.account.retrieve()Response20022 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's fee on this brand; null when none is set.
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
platformFeeobjectLucra's fee on ad spend for programs created now; a program keeps the terms current when it was created.
Show 3 child fieldsHide child fields
percentnumbersourceenumdefaultaccountversionstring
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
lucra.account.update({ body })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
percentnumberrequired
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenumrequiredad_spendgmvpercentnumberrequired
profilePicturefile_…nullablenamestringdescriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
typeenumbrandpartnerlistingobjectShow 3 child fieldsHide child fields
listedbooleanheadlinestringnullablecategoriesstring[]
versioninteger
Response20022 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's fee on this brand; null when none is set.
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
platformFeeobjectLucra's fee on ad spend for programs created now; a program keeps the terms current when it was created.
Show 3 child fieldsHide child fields
percentnumbersourceenumdefaultaccountversionstring
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 or platform; as a creator, your own work's ad results across brands
lucra.analytics.retrieve({ query })Query parameters
fromstringrequiredtostringrequiredmodeenumpaid: ad results. organic: creators' own posts' views and engagement, for the last 90 days at most.
paidorganiccampaigncamp_…submissionsub_…programprog_…creatorcrtr_…platformenummetatiktokgooglesnapchatinstagramgroupstringSplit each day by campaign, submission (the creative), creator and/or platform, e.g. group=campaign,submission.
Applications
/v1/applicationsList applications
lucra.applications.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
programprog_…creatorcrtr_…statusstringOne or more, comma-separated: pending, approved, rejected, withdrawn.
Response200A page of items, 14 fields each, and nextCursorShow
idappl_…programprog_…creatorcrtr_…statusenumpendingapprovedrejectedwithdrawnpayobjectnullablePay the brand set for this creator over the program's (PATCH `pay`); null when the program's pay applies. `acceptedAt` is 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 `payVersion` until 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
lucra.applications.retrieve({ path: { id } })Path parameters
idstringrequired
Response20014 fieldsShow
idappl_…programprog_…creatorcrtr_…statusenumpendingapprovedrejectedwithdrawnpayobjectnullablePay the brand set for this creator over the program's (PATCH `pay`); null when the program's pay applies. `acceptedAt` is 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 `payVersion` until 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
lucra.applications.create({ body })Body
programprog_…requiredcreatorcrtr_…
Response20114 fieldsShow
idappl_…programprog_…creatorcrtr_…statusenumpendingapprovedrejectedwithdrawnpayobjectnullablePay the brand set for this creator over the program's (PATCH `pay`); null when the program's pay applies. `acceptedAt` is 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 `payVersion` until 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)
lucra.applications.update({ path: { id }, body })Path parameters
idstringrequired
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
Response20014 fieldsShow
idappl_…programprog_…creatorcrtr_…statusenumpendingapprovedrejectedwithdrawnpayobjectnullablePay the brand set for this creator over the program's (PATCH `pay`); null when the program's pay applies. `acceptedAt` is 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 `payVersion` until 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 funds, or a creator's earnings
lucra.balance.retrieve()Response2002 fieldsShow
balancesobject[]Show 10 child fieldsHide child fields
currencystringLowercase ISO 4217 code, e.g. usd.
availableintegerA brand's funds free to commit to programs; a creator's earnings past their hold, sent to their Stripe balance within the hour once their identity is verified.
pendingintegerA brand's funding that hasn't settled; a creator's earnings not yet final.
heldintegerA brand's funds held for ad-spend usage charges; a creator's earnings on their hold.
reservedintegerA brand's funds held for its programs' creators; 0 for a creator.
spentintegerSpent from a brand's funds; 0 for a creator.
refundableintegerCan be refunded with POST /v1/balance/refunds; 0 for a creator.
paidintegerA creator's earnings sent to their Stripe balance, all time; 0 for an account.
withdrawableintegerIn this balance's Stripe account (a creator's, or an account's commissions), ready to withdraw with POST /v1/withdrawals.
instantWithdrawableintegerHow much of `withdrawable` can go out instantly, to a debit card.
withdrawalFeesobjectWhat 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/transactionsList every ledger line on the account
lucra.balance.transactions.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
typestringComma-separated transaction types, e.g. deposit,funding_refund.
programprog_…
Response200A page of items, 17 fields each, and nextCursorShow
idtxn_…typestringstatusstringamountintegerSigned, in cents: positive adds to the balance.
feeintegerIn cents.
netintegerSigned, in cents: `amount` less `fee`.
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_…nullabledepositdep_…nullableThe deposit this line funds, if any.
refundrfnd_…nullableThe refund this line is, if any.
occurredAtstring
/v1/balance/depositsAdd funds to the balance
lucra.balance.deposits.create({ body })Headers
Idempotency-KeystringrequiredUnique to this write; resend it to retry safely.
Body
netintegerrequiredIn cents, what the balance receives: more than $0.50, at most $999,999.99. A card's fee is charged on top.
methodenumbank: a free bank debit; card: adds Lucra's card fee to the charge.
bankcardcheckoutenumhosted (the default): pay at `checkoutUrl`; elements: pay in your own form with Stripe's Payment Element and `clientSecret`.
hostedelements
/v1/balance/depositsList deposits to the balance
lucra.balance.deposits.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
Response200A page of items, 10 fields each, and nextCursorShow
iddep_…amountintegerCharged to the payer, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
methodenumbank: a free bank debit; card: Lucra's card fee is charged on top of what the balance receives.
bankcardstatusenumpending until the payer pays and it settles; `net` is then available.
pendingavailablefailedpartially_refundedrefundeddisputedcheckoutUrlstringnullableStripe Checkout: send the payer here to pay; null for an elements checkout.
createdAtstringupdatedAtstring
/v1/balance/deposits/:idGet a deposit
lucra.balance.deposits.retrieve({ path: { id } })Path parameters
idstringrequired
Response20010 fieldsShow
iddep_…amountintegerCharged to the payer, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
methodenumbank: a free bank debit; card: Lucra's card fee is charged on top of what the balance receives.
bankcardstatusenumpending until the payer pays and it settles; `net` is then available.
pendingavailablefailedpartially_refundedrefundeddisputedcheckoutUrlstringnullableStripe Checkout: send the payer here to pay; null for an elements checkout.
createdAtstringupdatedAtstring
/v1/balance/refundsRefund available funds
lucra.balance.refunds.create({ body })Headers
Idempotency-KeystringrequiredUnique to this write; resend it to retry safely.
Body
amountintegerrequiredIn cents, up to the balance's `refundable`.
Response2018 fieldsShow
idrfnd_…amountintegerReturned to the cards and banks the deposits came from, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
statusenumprocessingsucceededfailedreversedcreatedAtstringupdatedAtstring
/v1/balance/refundsList refunds from the balance
lucra.balance.refunds.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
Response200A page of items, 8 fields each, and nextCursorShow
idrfnd_…amountintegerReturned to the cards and banks the deposits came from, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
statusenumprocessingsucceededfailedreversedcreatedAtstringupdatedAtstring
/v1/balance/refunds/:idGet a refund
lucra.balance.refunds.retrieve({ path: { id } })Path parameters
idstringrequired
Response2008 fieldsShow
idrfnd_…amountintegerReturned to the cards and banks the deposits came from, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
statusenumprocessingsucceededfailedreversedcreatedAtstringupdatedAtstring
Brands
/v1/brandsList the brands this key reaches, and a partner's brands whose relationship ended
lucra.brands.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
statusenumactiveended
Response200A page of items, 22 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 fee on this brand; null when none is set.
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
platformFeeobjectLucra's fee on ad spend for programs created now; a program keeps the terms current when it was created.
Show 3 child fieldsHide child fields
percentnumbersourceenumdefaultaccountversionstring
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
lucra.brands.retrieve({ path: { id } })Path parameters
idstringrequired
Response20022 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's fee on this brand; null when none is set.
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
platformFeeobjectLucra's fee on ad spend for programs created now; a program keeps the terms current when it was created.
Show 3 child fieldsHide child fields
percentnumbersourceenumdefaultaccountversionstring
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
lucra.brands.create({ body })Body
namestringrequiredbrandFeeobjectShow 2 child fieldsHide child fields
ofenumrequiredad_spendgmvpercentnumberrequired
emailstringphonestring
Response20122 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's fee on this brand; null when none is set.
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
platformFeeobjectLucra's fee on ad spend for programs created now; a program keeps the terms current when it was created.
Show 3 child fieldsHide child fields
percentnumbersourceenumdefaultaccountversionstring
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
lucra.brands.update({ path: { id }, body })Path parameters
idstringrequired
Body
brandFeeobjectnullableShow 2 child fieldsHide child fields
ofenumrequiredad_spendgmvpercentnumberrequired
profilePicturefile_…nullablenamestringdescriptionstringnullablerecruitmentobjectShow 2 child fieldsHide child fields
headlinestringnullabledescriptionstringnullable
versioninteger
Response20022 fieldsShow
idacct_…typeenumbrandpartnernamestringstatusenumended: a brand whose relationship with your partner account ended; it reads, but no longer changes.
activeendedmanagedByacct_…nullablebrandFeeobjectnullableThe managing partner's fee on this brand; null when none is set.
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
platformFeeobjectLucra's fee on ad spend for programs created now; a program keeps the terms current when it was created.
Show 3 child fieldsHide child fields
percentnumbersourceenumdefaultaccountversionstring
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
lucra.campaigns.create({ body })Body
namestringrequiredobjectiveenumDefaults to the account's (GET /v1/ad-defaults), conversions unless set.
conversionstrafficawarenessdestinationobjectrequiredShow 2 child fieldsHide child fields
typestringrequiredvaluestring
budgetobjectrequiredbillingLimitintegerStop spending once the campaign has spent this much, in cents.
scheduleobjectrequiredShow 2 child fieldsHide child fields
startDatestringrequiredendDatestring
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's `adSets`, 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's `ads`, to keep it.
creativesub_…requirednamestring
adobjectrequiredShow 3 child fieldsHide child fields
primaryTextstringrequiredcallToActionenumrequiredbook_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribeheadlinestring
optimizationEventenuminstallpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontactsettingsobjectShow 9 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.
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: your measurement partner's click tracker.
impressionTrackingUrlstringTikTok: your measurement partner's impression tracker.
connectionconn_…requiredidentityenumRun ads under the brand's identity (default) or the creator's.
brandcreatorlaunchbooleanCreate it on the ad platform now, paused until you PATCH status "live" (the default), or false to save it ready to create later.
Response20127 fieldsShow
idcamp_…namestringstatusenumdraftreadylivepausedneeds_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
audienceobjectShow 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 6 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
feenumbernullableThe total usage fee on spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
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
lucra.campaigns.copies.create({ path: { id }, body })Path parameters
idstringrequired
Body
namestringDefaults to the source's name with " (copy)".
launchbooleanPublish the copy now, or (default) save it ready to launch with PATCH status "live".
Response20127 fieldsShow
idcamp_…namestringstatusenumdraftreadylivepausedneeds_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
audienceobjectShow 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 6 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
feenumbernullableThe total usage fee on spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
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
lucra.campaigns.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
statusenumdraftreadylivepausedneeds_attentionarchivedplatformenummetatiktokgooglesnapchatconnectionconn_…
Response200A page of items, 27 fields each, and nextCursorShow
idcamp_…namestringstatusenumdraftreadylivepausedneeds_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
audienceobjectShow 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 6 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
feenumbernullableThe total usage fee on spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
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
lucra.campaigns.retrieve({ path: { id } })Path parameters
idstringrequired
Response20027 fieldsShow
idcamp_…namestringstatusenumdraftreadylivepausedneeds_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
audienceobjectShow 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 6 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
feenumbernullableThe total usage fee on spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
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
lucra.campaigns.update({ path: { id }, body })Path parameters
idstringrequired
Body
namestringobjectiveenumconversions (default) optimizes for `optimizationEvent`; traffic (link clicks) and awareness (reach) run on Meta websites (beta).
conversionstrafficawarenessdestinationobjectShow 2 child fieldsHide child fields
typestringrequiredvaluestring
budgetobjectbillingLimitintegerStop spending once the campaign has spent this much, in cents.
scheduleobjectShow 2 child fieldsHide child fields
startDatestringrequiredendDatestring
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's `adSets`, 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's `ads`, to keep it.
creativesub_…requirednamestring
adobjectShow 3 child fieldsHide child fields
primaryTextstringrequiredcallToActionenumrequiredbook_nowcontact_usdownloadlearn_moreshop_nowsign_upsubscribeheadlinestring
optimizationEventenuminstallpurchasesubscriptiontrial_startinitiate_checkoutadd_to_cartview_contentcomplete_registrationleadcontactsettingsobjectShow 9 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.
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: your measurement partner's click tracker.
impressionTrackingUrlstringTikTok: your measurement partner's impression tracker.
statusenumlive publishes a ready campaign, resumes a paused one, or retries a launch that needs attention.
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_…requiredbudgetintegerrequired
pendingChangestringAs the brand: approves the change a partner made, which `pendingChange` shows awaiting approval.
approvedversioninteger
Response20027 fieldsShow
idcamp_…namestringstatusenumdraftreadylivepausedneeds_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
audienceobjectShow 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 6 child fieldsHide child fields
modelenumad_spendattributed_revenueleadcreatorSharenumbernullableThe creator's share of spend or revenue, in percent.
feenumbernullableThe total usage fee on spend or revenue, in percent.
leadAmountintegernullableWhat a creator earns per lead, in cents.
capintegernullableThe most a creator earns from the campaign, in cents.
revenueEventstringnullable
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
lucra.adFields.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
platformenumAlso returns the universal settings unless `universal`.
metatiktokgooglesnapchatuniversalresourceenumcampaignad_setadcreativestatusenumimplementedplannedprovider_gatedread_onlydeprecated
Ad defaults
/v1/ad-defaultsGet what the account's new campaigns start with
lucra.adDefaults.retrieve()/v1/ad-defaultsChange what the account's new campaigns start with
lucra.adDefaults.update({ body })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: your measurement partner's click tracker.
impressionTrackingUrlstringTikTok: your measurement partner's impression tracker.
Ad audiences
/v1/ad-audiencesList an ad account's saved audiences (Meta custom and lookalike audiences, TikTok audiences)
lucra.adAudiences.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
connectionconn_…requiredA Meta or TikTok ad account `conn_` from GET /v1/connections.
Ad interests
/v1/ad-interestsSearch the interests an ad set can target on Meta or TikTok
lucra.adInterests.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
connectionconn_…requiredA Meta or TikTok ad account `conn_` from GET /v1/connections.
qstringrequiredWhat to search for, e.g. running.
Ad sets
/v1/ad-setsList ad sets (Meta ad sets, TikTok and Google ad groups, Snapchat ad squads)
lucra.adSets.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
campaigncamp_…platformenummetatiktokgooglesnapchatstatusenumdraftactivepausedarchiveddeletedunknown
/v1/ad-sets/:idGet an ad set
lucra.adSets.retrieve({ path: { id } })Path parameters
idstringrequired
/v1/ad-sets/:idRename, pause, resume, archive or re-budget an ad set on its platform
lucra.adSets.update({ path: { id }, body })Path parameters
idstringrequired
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
lucra.adSets.copies.create({ path: { id }, body })Path parameters
idstringrequired
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
lucra.ads.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
campaigncamp_…platformenummetatiktokgooglesnapchatstatusenumdraftactivepausedarchiveddeletedunknownadSetadset_…
/v1/ads/:idGet an ad
lucra.ads.retrieve({ path: { id } })Path parameters
idstringrequired
/v1/ads/:idRename, pause, resume or archive an ad on its platform
lucra.ads.update({ path: { id }, body })Path parameters
idstringrequired
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
lucra.ads.copies.create({ path: { id }, body })Path parameters
idstringrequired
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
lucra.connections.retrieve({ path: { id } })Path parameters
idstringrequired
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; `canDisconnect` covers 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
lucra.connections.setup.retrieve({ path: { id }, query })Path parameters
idstringrequired
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
lucra.connections.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
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; `canDisconnect` covers 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
lucra.connections.syncs.create({ path: { id } })Path parameters
idstringrequired
/v1/connectionsConnect a platform, payouts or a card: returns the hosted page to send the person to
lucra.connections.create({ body })Body
providerenumrequiredA 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.
ATBEBGCAHRCYCZDKEEFIFRDEGRHUISIEITLVLILTLUMTNLNOPLPTROSKSIESSECHGBUSreturnUrlstringWhere the person comes back to, with `status=connected` or `status=error` added: your own https page (its origin must be on the key's embed origins), a page of the Lucra app (a path), or `lucra-creators:` for the Lucra iOS app. Defaults to a hosted done page (for stripe and card, the matching settings page).
checkoutenumWith card: hosted (the default) returns Stripe's page at `url` (its billing portal once a card is saved); elements returns `clientSecret` to save a new card in your own form with Stripe's Payment Element (Checkout elements, setup mode), which then replaces the card charged.
hostedelements
Response2013 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 card and `checkout: elements`: the Checkout Session's client secret for Stripe's Payment Element (`initCheckoutElementsSdk`); null otherwise. Stripe's setup webhook saves the card.
expiresAtstringnullableWhen 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
lucra.connections.update({ path: { id }, body })Path parameters
idstringrequired
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; `canDisconnect` covers 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
lucra.connections.posts.list({ path: { id } })Path parameters
idstringrequired
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
lucra.creators.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
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
Response200A page of items, 31 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
trustobjectShow 1 child fieldHide child fields
scorenumber
performanceobjectnullableDaily 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's `file_…`.
filefile_…nullableurlstringnullabletitlestringnullablepublishedAtstringnullabledurationLabelstringnullablethumbnailUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
videoUrlstringnullable
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 13 child fieldsHide child fields
headlinestringnullablespecialtystringnullableagenumbernullablegenderstringnullablecategoriesstring[]creativeStylesstring[]interestsstring[]requestStatusenumnullableYour account's latest connection request to them.
pendingaccepteddeclinedtrustobjectnullableShow 5 child fieldsHide child fields
approvalQualitynumberbrandReliabilitynumberdeliveryReliabilitynumberpaidPerformancenumbercalculatedAtstringnullable
audiencestringnullablelastActivestringnullableresponseTimestringnullablesubmissionsobject[]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 9 child fieldsHide child fields
birthDatestringnullablegenderstringnullableinterestsstring[]creativeStylesstring[]locationDetailsobjectnullableShow 9 child fieldsHide child fields
citystringcountryCodestringcountryNamestringdisplayNamestringgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
onboardingCompletedAtstringnullablehiddenFromacct_…[]Partners that hide this creator from their Discover.
trustobjectShow 7 child fieldsHide child fields
scorenumberapprovalQualitynumberbrandReliabilitynumberdeliveryReliabilitynumberpaidPerformancenumbernextActionstringcalculatedAtstringnullable
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
lucra.creators.retrieve({ path: { id } })Path parameters
idstringrequired
Response20031 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
trustobjectShow 1 child fieldHide child fields
scorenumber
performanceobjectnullableDaily 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's `file_…`.
filefile_…nullableurlstringnullabletitlestringnullablepublishedAtstringnullabledurationLabelstringnullablethumbnailUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
videoUrlstringnullable
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 13 child fieldsHide child fields
headlinestringnullablespecialtystringnullableagenumbernullablegenderstringnullablecategoriesstring[]creativeStylesstring[]interestsstring[]requestStatusenumnullableYour account's latest connection request to them.
pendingaccepteddeclinedtrustobjectnullableShow 5 child fieldsHide child fields
approvalQualitynumberbrandReliabilitynumberdeliveryReliabilitynumberpaidPerformancenumbercalculatedAtstringnullable
audiencestringnullablelastActivestringnullableresponseTimestringnullablesubmissionsobject[]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 9 child fieldsHide child fields
birthDatestringnullablegenderstringnullableinterestsstring[]creativeStylesstring[]locationDetailsobjectnullableShow 9 child fieldsHide child fields
citystringcountryCodestringcountryNamestringdisplayNamestringgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
onboardingCompletedAtstringnullablehiddenFromacct_…[]Partners that hide this creator from their Discover.
trustobjectShow 7 child fieldsHide child fields
scorenumberapprovalQualitynumberbrandReliabilitynumberdeliveryReliabilitynumberpaidPerformancenumbernextActionstringcalculatedAtstringnullable
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
lucra.creators.create({ body })Body
emailstringrequirednamestringphonestringvisibilityenumprivatenetwork
Response20131 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
trustobjectShow 1 child fieldHide child fields
scorenumber
performanceobjectnullableDaily 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's `file_…`.
filefile_…nullableurlstringnullabletitlestringnullablepublishedAtstringnullabledurationLabelstringnullablethumbnailUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
videoUrlstringnullable
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 13 child fieldsHide child fields
headlinestringnullablespecialtystringnullableagenumbernullablegenderstringnullablecategoriesstring[]creativeStylesstring[]interestsstring[]requestStatusenumnullableYour account's latest connection request to them.
pendingaccepteddeclinedtrustobjectnullableShow 5 child fieldsHide child fields
approvalQualitynumberbrandReliabilitynumberdeliveryReliabilitynumberpaidPerformancenumbercalculatedAtstringnullable
audiencestringnullablelastActivestringnullableresponseTimestringnullablesubmissionsobject[]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 9 child fieldsHide child fields
birthDatestringnullablegenderstringnullableinterestsstring[]creativeStylesstring[]locationDetailsobjectnullableShow 9 child fieldsHide child fields
citystringcountryCodestringcountryNamestringdisplayNamestringgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
onboardingCompletedAtstringnullablehiddenFromacct_…[]Partners that hide this creator from their Discover.
trustobjectShow 7 child fieldsHide child fields
scorenumberapprovalQualitynumberbrandReliabilitynumberdeliveryReliabilitynumberpaidPerformancenumbernextActionstringcalculatedAtstringnullable
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
lucra.creators.update({ path: { id }, body })Path parameters
idstringrequired
Body
visibilityenumprivatenetworkprofilePicturefile_…nullabletagsstring[]notesstringnullablestatusenumlivepausedremovedbrandsacct_…[]A partner's roster creator works with exactly these client brands; brands left out stop working with them.
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
citystringrequiredcountryCodestringrequiredcountryNamestringrequireddisplayNamestringrequiredgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
namestringplatformHandlesobjectShow 2 child fieldsHide child fields
instagramstringtiktokstring
referenceVideoSelectionsobject[]Show 10 child fieldsHide child fields
durationLabelstringmediaAssetIdstringplatformenumrequiredinstagramtiktokuploadpublishedAtstringsourceContentIdstringrequiredsourceUrlstringthumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdstringrequiredurlstringwidthintegernullableheightintegernullableblurHashstringnullable
thumbnailUrlstringtitlestringvideoUrlstring
referenceVideosstring[]pictureFromenumUse this connected account's profile photo as the creator's picture.
instagramtiktokversioninteger
Response20031 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
trustobjectShow 1 child fieldHide child fields
scorenumber
performanceobjectnullableDaily 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's `file_…`.
filefile_…nullableurlstringnullabletitlestringnullablepublishedAtstringnullabledurationLabelstringnullablethumbnailUrlstringnullablethumbnailImageobjectnullableShow 5 child fieldsHide child fields
fileIdfile_…nullableurlstringwidthnumbernullableheightnumbernullableblurHashstringnullable
videoUrlstringnullable
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 13 child fieldsHide child fields
headlinestringnullablespecialtystringnullableagenumbernullablegenderstringnullablecategoriesstring[]creativeStylesstring[]interestsstring[]requestStatusenumnullableYour account's latest connection request to them.
pendingaccepteddeclinedtrustobjectnullableShow 5 child fieldsHide child fields
approvalQualitynumberbrandReliabilitynumberdeliveryReliabilitynumberpaidPerformancenumbercalculatedAtstringnullable
audiencestringnullablelastActivestringnullableresponseTimestringnullablesubmissionsobject[]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 9 child fieldsHide child fields
birthDatestringnullablegenderstringnullableinterestsstring[]creativeStylesstring[]locationDetailsobjectnullableShow 9 child fieldsHide child fields
citystringcountryCodestringcountryNamestringdisplayNamestringgeonamesIdstringlatitudenumberlongitudenumberregionCodestringregionNamestring
onboardingCompletedAtstringnullablehiddenFromacct_…[]Partners that hide this creator from their Discover.
trustobjectShow 7 child fieldsHide child fields
scorenumberapprovalQualitynumberbrandReliabilitynumberdeliveryReliabilitynumberpaidPerformancenumbernextActionstringcalculatedAtstringnullable
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
lucra.files.create({ query, body })Query parameters
purposeenumrequiredsubmissionproduct_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.
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_incomplete` when 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
lucra.files.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
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.
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_incomplete` when 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
lucra.files.retrieve({ path: { id } })Path parameters
idstringrequired
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_incomplete` when 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
lucra.files.update({ path: { id }, body })Path parameters
idstringrequired
Body
statusenumrequiredprocessing: 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_incomplete` when 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
lucra.messages.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
threadthr_…
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
lucra.messages.create({ body })Body
threadthr_…requiredbodystringfilesfile_…[]Attachments: `chat_attachment` files.
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
lucra.messages.update({ path: { id }, body })Path parameters
idstringrequired
Body
versionintegerThe message's `version` as 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
emojistringrequiredactivebooleanrequiredtrue adds the reaction, false removes it.
reportobjectReport the message to Lucra.
Show 2 child fieldsHide child fields
reasonenumrequiredspamharassmentunsafe_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
lucra.payments.create({ body })Headers
Idempotency-KeystringrequiredUnique to this write; resend it to retry safely.
Body
creatorcrtr_…requirednetintegerrequiredIn cents, what the creator receives; Lucra's fee is charged on top.
notestring
Response20115 fieldsShow
idpay_…creatorcrtr_…amountintegerCharged to the brand: what the creator receives (`net`) plus Lucra's fee, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, 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 `status` is 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
lucra.payments.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
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
Response200A page of items, 15 fields each, and nextCursorShow
idpay_…creatorcrtr_…amountintegerCharged to the brand: what the creator receives (`net`) plus Lucra's fee, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, 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 `status` is 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
lucra.payments.retrieve({ path: { id } })Path parameters
idstringrequired
Response20015 fieldsShow
idpay_…creatorcrtr_…amountintegerCharged to the brand: what the creator receives (`net`) plus Lucra's fee, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, 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 `status` is 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
lucra.payments.update({ path: { id }, body })Path parameters
idstringrequired
Headers
Idempotency-KeystringrequiredUnique to this write; resend it to retry safely.
Response20015 fieldsShow
idpay_…creatorcrtr_…amountintegerCharged to the brand: what the creator receives (`net`) plus Lucra's fee, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, 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 `status` is 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/payoutsList payouts: to creators from this brand's earnings, received by this account, or (as a creator) the creator's own
lucra.payouts.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
directionenumsentreceivedcreatorcrtr_…statusstringOne or more, comma-separated: pending, submitted, paid, failed, reversed, unknown.
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; `net` is sent to the recipient's Stripe balance, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpendingsubmittedpaidfailedreversedunknownfailureMessagestringnullablecreatedAtstringupdatedAtstring
/v1/payouts/:idGet a payout
lucra.payouts.retrieve({ path: { id } })Path parameters
idstringrequired
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; `net` is sent to the recipient's Stripe balance, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
statusenumpendingsubmittedpaidfailedreversedunknownfailureMessagestringnullablecreatedAtstringupdatedAtstring
Earnings
/v1/earningsList a creator's earnings
lucra.earnings.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
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_…
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 receives `net`, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
statusenumheld until holdUntilAt, then available, then paid: sent to the creator's Stripe balance (once their identity is verified), to withdraw.
pendingheldavailablepaidholdUntilAtstringnullableoccurredAtstring
/v1/earnings/:idGet one of a creator's earnings
lucra.earnings.retrieve({ path: { id } })Path parameters
idstringrequired
Response20013 fieldsShow
idern_…programprog_…nullableaccountacct_…The brand that paid it.
submissionsub_…nullableretainerret_…nullablesourceenumpaid_adsorganicsubmissionprogrambonusretainerreferraladjustmentpartner_commissionamountintegerEarned before any partner take rate (`fee`); the creator receives `net`, in cents.
feeintegerTaken from `amount`, in cents.
netinteger`amount` less `fee`, in cents.
currencystringLowercase ISO 4217 code, e.g. usd.
statusenumheld until holdUntilAt, then available, then paid: sent to the creator's Stripe balance (once their identity is verified), to withdraw.
pendingheldavailablepaidholdUntilAtstringnullableoccurredAtstring
Withdrawals
/v1/withdrawalsWithdraw from the balance to the bank account or debit card
lucra.withdrawals.create({ body })Headers
Idempotency-KeystringrequiredUnique 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.
netinteger`amount` less `fee`: 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
lucra.withdrawals.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
statusstringOne or more, comma-separated: pending, in_transit, paid, failed.
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.
netinteger`amount` less `fee`: 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
lucra.withdrawals.retrieve({ path: { id } })Path parameters
idstringrequired
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.
netinteger`amount` less `fee`: 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
lucra.cities.list({ query })Query parameters
qstringrequiredA city name, or the start of one.
countrystringOnly cities in this country (ISO 3166-1 alpha-2, e.g. US).
limitintegerCities per page.
cursorstring`nextCursor` from 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
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
lucra.keys.current.update({ body })Body
webhookUrlstringnullablerequiredA 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
lucra.events.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
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
lucra.agreements.acceptances.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
agreementagr_…creatorcrtr_…statusenumpending: offers and invitations waiting on a creator; only a creator lists these.
acceptedpending
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
lucra.agreements.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
statusstringOne or more, comma-separated: active, archived.
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 `version` to reject a change based on a stale read.
createdAtstringupdatedAtstring
/v1/agreements/:idGet an agreement
lucra.agreements.retrieve({ path: { id } })Path parameters
idstringrequired
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 `version` to reject a change based on a stale read.
createdAtstringupdatedAtstring
/v1/agreements/:id/versionsList an agreement's versions, newest first
lucra.agreements.versions.list({ path: { id }, query })Path parameters
idstringrequired
Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
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
lucra.agreements.versions.retrieve({ path: { id, number } })Path parameters
idstringrequirednumberstringrequired
Response2009 fieldsShow
agreementagr_…versionintegerfilefile_…nullablefileNamestringsizeintegersha256stringapplicabilityenum[]creator_relationshipprogram_applicationprogram_enrollmentretainercontent_submissioncreatedAtstringurlstringnullableA short-lived link to the PDF.
/v1/agreementsPublish an agreement
lucra.agreements.create({ body })Body
filefile_…requiredA ready PDF uploaded with POST /v1/files?purpose=agreement.
titlestringrequireddescriptionstringnullableapplicabilityenum[]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 `version` to reject a change based on a stale read.
createdAtstringupdatedAtstring
/v1/agreements/:id/versionsPublish a new version of an agreement
lucra.agreements.versions.create({ path: { id }, body })Path parameters
idstringrequired
Body
filefile_…requiredA ready PDF uploaded with POST /v1/files?purpose=agreement.
titlestringrequireddescriptionstringnullableapplicabilityenum[]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 `version` to reject a change based on a stale read.
createdAtstringupdatedAtstring
/v1/agreements/:idChange where an agreement is required, or archive it
lucra.agreements.update({ path: { id }, body })Path parameters
idstringrequired
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 `version` to 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
lucra.threads.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
kindenumdirectprogramsupportprogramprog_…
Response200A page of items, 14 fields each, and nextCursorShow
idstringkindenumdirectprogramsupportaccountstringnullableprogramstringnullablesupportobjectnullableShow 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, a program's group chat or a Lucra Support thread; an existing one is returned
lucra.threads.create({ body })Body
kindenumrequireddirect: 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_attachment` files (file_).
Response20114 fieldsShow
idstringkindenumdirectprogramsupportaccountstringnullableprogramstringnullablesupportobjectnullableShow 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=
lucra.threads.retrieve({ path: { id } })Path parameters
idstringrequired
Response20014 fieldsShow
idstringkindenumdirectprogramsupportaccountstringnullableprogramstringnullablesupportobjectnullableShow 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
lucra.posts.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
programprog_…creatorcrtr_…platformenuminstagramtiktokstatusstringDefaults to every status but archived.
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
lucra.posts.retrieve({ path: { id } })Path parameters
idstringrequired
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
lucra.posts.update({ path: { id }, body })Path parameters
idstringrequired
Body
versionintegertagobjectShow 2 child fieldsHide child fields
namestringrequiredcolorenumrequiredgreydark_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
lucra.adAuthorizations.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
submissionsub_…platformenumtiktokmetastatusstringOne or more, comma-separated: requested, granted, revoked, expired.
Response200A page of items, 14 fields each, and nextCursorShow
idadauth_…submissionsub_…creatorcrtr_…accountacct_…The brand that asks.
brandNamestringplatformenumtiktokmetastatusenumrequested by the brand, granted by the creator, revoked by either; expired once `expiresAt` passes.
requestedgrantedrevokedexpiredcodestringnullableThe TikTok Spark code the creator granted with; null for Meta and until granted.
authorizedAtstringnullableexpiresAtstringnullablerevokedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/ad-authorizations/:idGet an ad authorization
lucra.adAuthorizations.retrieve({ path: { id } })Path parameters
idstringrequired
Response20014 fieldsShow
idadauth_…submissionsub_…creatorcrtr_…accountacct_…The brand that asks.
brandNamestringplatformenumtiktokmetastatusenumrequested by the brand, granted by the creator, revoked by either; expired once `expiresAt` passes.
requestedgrantedrevokedexpiredcodestringnullableThe TikTok Spark code the creator granted with; null for Meta and until granted.
authorizedAtstringnullableexpiresAtstringnullablerevokedAtstringnullableversionintegerSend 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 TikTok Spark or Meta partnership ad
lucra.adAuthorizations.create({ body })Body
submissionsub_…requiredAn approved submission of a creator.
platformenumrequiredtiktokmeta
Response20114 fieldsShow
idadauth_…submissionsub_…creatorcrtr_…accountacct_…The brand that asks.
brandNamestringplatformenumtiktokmetastatusenumrequested by the brand, granted by the creator, revoked by either; expired once `expiresAt` passes.
requestedgrantedrevokedexpiredcodestringnullableThe TikTok Spark code the creator granted with; null for Meta and until granted.
authorizedAtstringnullableexpiresAtstringnullablerevokedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/ad-authorizations/:idGrant an ad authorization as its creator, or revoke it
lucra.adAuthorizations.update({ path: { id }, body })Path parameters
idstringrequired
Body
statusenumrequiredgrantedrevokedcodestringWith granted on TikTok: the Spark code the creator generated for the post.
expiresAtstringWith granted: when the creator's authorization ends, as they set it on the platform.
versioninteger
Response20014 fieldsShow
idadauth_…submissionsub_…creatorcrtr_…accountacct_…The brand that asks.
brandNamestringplatformenumtiktokmetastatusenumrequested by the brand, granted by the creator, revoked by either; expired once `expiresAt` passes.
requestedgrantedrevokedexpiredcodestringnullableThe TikTok Spark code the creator granted with; null for Meta and until granted.
authorizedAtstringnullableexpiresAtstringnullablerevokedAtstringnullableversionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
Embeds
/v1/embedsOpen Lucra UI for a brand or creator, hosted or embedded
lucra.embeds.create({ body })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
primarystringrequired
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
lucra.embeds.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
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
lucra.embeds.retrieve({ path: { id } })Path parameters
idstringrequired
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
lucra.embeds.update({ path: { id }, body })Path parameters
idstringrequired
Body
statusstringrequiredEnds 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
lucra.products.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
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
lucra.products.create({ body })Body
namestringrequiredproductTypestringurlstringdescriptionstringskustringimagefile_…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
lucra.products.retrieve({ path: { id } })Path parameters
idstringrequired
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
lucra.products.update({ path: { id }, body })Path parameters
idstringrequired
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
lucra.retainers.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
creatorcrtr_…
Response200A page of items, 19 fields each, and nextCursorShow
idret_…creatorcrtr_…accountacct_…The brand that offers the retainer.
brandNamestringbrandAvatarUrlstringnullablepayobjectShow 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; `accepted` once 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
lucra.retainers.retrieve({ path: { id } })Path parameters
idstringrequired
Response20019 fieldsShow
idret_…creatorcrtr_…accountacct_…The brand that offers the retainer.
brandNamestringbrandAvatarUrlstringnullablepayobjectShow 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; `accepted` once 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
lucra.retainers.create({ body })Headers
Idempotency-KeystringrequiredUnique to this write; resend it to retry safely.
Body
creatorcrtr_…requiredpayobjectrequiredShow 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.
scheduleobjectrequiredapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
deliverablesstringnotesstring
Response20119 fieldsShow
idret_…creatorcrtr_…accountacct_…The brand that offers the retainer.
brandNamestringbrandAvatarUrlstringnullablepayobjectShow 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; `accepted` once 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
lucra.retainers.update({ path: { id }, body })Path parameters
idstringrequired
Body
statusenumrequiredacceptedrejectedcancelingversioninteger
Response20019 fieldsShow
idret_…creatorcrtr_…accountacct_…The brand that offers the retainer.
brandNamestringbrandAvatarUrlstringnullablepayobjectShow 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; `accepted` once 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
lucra.programs.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
scopestringThe Lucra Network's open programs instead of your own.
networkvisibilityenuminvitenetworkstatusenumdraftopenpausedclosedarchived
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 TikTok Spark code or a Meta partnership) before a submission runs as an 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 3 child fieldsHide child fields
amountnumbernullableThe planned budget.
reservednumbernullableFunds held from the balance for the program's creators.
feeCapnumbernullableThe most a paid-ads program's fees may take from the reserved funds; null until funds are reserved.
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
lucra.programs.retrieve({ path: { id } })Path parameters
idstringrequired
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 TikTok Spark code or a Meta partnership) before a submission runs as an 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 3 child fieldsHide child fields
amountnumbernullableThe planned budget.
reservednumbernullableFunds held from the balance for the program's creators.
feeCapnumbernullableThe most a paid-ads program's fees may take from the reserved funds; null until funds are reserved.
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
lucra.programs.create({ body })Body
namestringrequiredtypeenumrequiredorganicpaid_adsvisibilityenumrequiredinvitenetworkbriefstringplatformsenum[]instagramtiktokpaidSocialPlatformsenum[]instagramtiktokallowManualOrganicUploadbooleanallowPaidPromotionbooleanallowPaidSocialUploadsbooleanrequireAdAuthorizationbooleansubmissionLimitsobjectShow 4 child fieldsHide child fields
modeenumlimitedunlimitedmaxintegerconcurrentModeenumlimitedunlimitedconcurrentMaxinteger
payobjectrequiredShow 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.
scheduleobjectrequiredapprovalenumautomatic 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 3 child fieldsHide child fields
amountintegerreservedintegerfeeCapinteger
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 TikTok Spark code or a Meta partnership) before a submission runs as an 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 3 child fieldsHide child fields
amountnumbernullableThe planned budget.
reservednumbernullableFunds held from the balance for the program's creators.
feeCapnumbernullableThe most a paid-ads program's fees may take from the reserved funds; null until funds are reserved.
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
lucra.programs.update({ path: { id }, body })Path parameters
idstringrequired
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.
scheduleobjectrequiredapprovalenumautomatic pays each period on its own; manual waits for the brand to approve the calculated amount.
automaticmanual
budgetobjectShow 3 child fieldsHide child fields
amountintegerreservedintegerfeeCapinteger
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 TikTok Spark code or a Meta partnership) before a submission runs as an 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 3 child fieldsHide child fields
amountnumbernullableThe planned budget.
reservednumbernullableFunds held from the balance for the program's creators.
feeCapnumbernullableThe most a paid-ads program's fees may take from the reserved funds; null until funds are reserved.
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
lucra.samples.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
productprod_…creatorcrtr_…statusstringOne or more, comma-separated: requested, approved, rejected, shipping, shipped, failed.
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
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
lucra.samples.retrieve({ path: { id }, query })Path parameters
idstringrequired
Query parameters
expandstringAs the creator: `shipment.accessCode` whole 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
lucra.samples.update({ path: { id }, body })Path parameters
idstringrequired
Body
statusenumrequiredapprovedrejectedversioninteger
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
lucra.submissions.list({ query })Query parameters
limitintegercursorstringcreatedAfterstringOnly items created at or after this time.
createdBeforestringOnly items created before this time.
programprog_…creatorcrtr_…statusstringOne or more, comma-separated: pending, revision_requested, approved, live, rejected, measuring, withdrawn, archived.
Response200A page of items, 18 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=archived` is 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 2 child fieldsHide child fields
statusenumcompletedfailedpendingskippedunsupportedtextstringnullable
adsobjectnullableShow 4 child fieldsHide child fields
identityenumnullablecreatorbrandlaunchedOnstring[]ownershipstringnullableprogramTypestringnullable
adAuthorizationobjectnullableThe newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
idadauth_…platformenumtiktokmetastatusenumrequestedgrantedrevokedexpiredauthorizedAtstringnullableexpiresAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring
/v1/submissions/:idGet a submission
lucra.submissions.retrieve({ path: { id } })Path parameters
idstringrequired
Response20018 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=archived` is 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 2 child fieldsHide child fields
statusenumcompletedfailedpendingskippedunsupportedtextstringnullable
adsobjectnullableShow 4 child fieldsHide child fields
identityenumnullablecreatorbrandlaunchedOnstring[]ownershipstringnullableprogramTypestringnullable
adAuthorizationobjectnullableThe newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
idadauth_…platformenumtiktokmetastatusenumrequestedgrantedrevokedexpiredauthorizedAtstringnullableexpiresAtstringnullable
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 to its library
lucra.submissions.create({ body })Body
programprog_…The program the work is for; required for a creator.
filefile_…requirednotestringpostUrlstringThe 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
disclosureIncludedbooleanrequiredexperienceTruthfulbooleanrequirednoUnapprovedClaimsbooleanrequiredacceptedAgreementsobject[]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_…requiredversionintegerrequired
namestringA brand library video's title; defaults to its file name.
Response20118 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=archived` is 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 2 child fieldsHide child fields
statusenumcompletedfailedpendingskippedunsupportedtextstringnullable
adsobjectnullableShow 4 child fieldsHide child fields
identityenumnullablecreatorbrandlaunchedOnstring[]ownershipstringnullableprogramTypestringnullable
adAuthorizationobjectnullableThe newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
idadauth_…platformenumtiktokmetastatusenumrequestedgrantedrevokedexpiredauthorizedAtstringnullableexpiresAtstringnullable
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
lucra.submissions.update({ path: { id }, body })Path parameters
idstringrequired
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.
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
Response20018 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=archived` is 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 2 child fieldsHide child fields
statusenumcompletedfailedpendingskippedunsupportedtextstringnullable
adsobjectnullableShow 4 child fieldsHide child fields
identityenumnullablecreatorbrandlaunchedOnstring[]ownershipstringnullableprogramTypestringnullable
adAuthorizationobjectnullableThe newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
idadauth_…platformenumtiktokmetastatusenumrequestedgrantedrevokedexpiredauthorizedAtstringnullableexpiresAtstringnullable
versionintegerSend it back on PATCH to reject edits based on a stale read.
createdAtstringupdatedAtstring