Submissions · Docs

A submission is a creator's video in a program. In an organic program it's also linked to the post where it went live, and Lucra measures that post's views.

Submit work

First upload the video with purpose=submission. Then submit it, acting as the creator:

TypeScript

await lucra.as("crtr_026UYfiw1Y6OvUpuKWiOpeL").submissions.create({
  body: {
    program: "prog_00lhuAJjQgdtNt5WnqTBc95",
    file: "file_03d3QVSYynIFwgmYzYd7opT",
    note: "First cut",
  },
})

In an organic program, add postUrl: the Instagram or TikTok post the video went live as.
To resubmit after a revision request, send revisionOf with the original sub_… ID.
Submitting accepts any agreements the brand requires for submissions.

A post in an organic program is approved or rejected once its measurement ends; approving it pays the creator on its measured views. Then release the payment with { "payment": "approved" }. Only the brand's owners and admins, or its own key, can do that.

Brand videos

A brand can add its own finished video to its library: upload it with purpose=ad_creative, then create a submission with { "file", "name" } and no program.

Endpoints

GET/v1/submissions

As creatorread

List submissions

const { data } = await lucra.submissions.list({
  query: { program: "prog_…" },
})

Query parameters

programprog_…
creatorcrtr_…
statusstring
One or more, comma-separated: pending, revision_requested, approved, live, rejected, measuring, withdrawn, archived.

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 19 fields each, and nextCursorShow

idsub_…
typeenum
post: the creator's published Instagram or TikTok post; video: an uploaded video.
videopost
programprog_…nullable
creatorcrtr_…nullable
revisionOfsub_…nullable
statusenum
A 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_requestedapprovedliverejectedmeasuringwithdrawnarchived
feedbackstringnullable
The brand's note with its latest review, such as what to change in a revision.
shortIdstringnullable
The short ID shown in the app and ad names.
submittedAtstringnullable
tagsstring[]
mediaobjectnullable
Show 6 child fieldsHide child fields
- videoUrlstringnullable
- thumbnailUrlstringnullable
- durationSecondsnumbernullable
- fileNamestringnullable
- sizenumbernullable
- contentTypestringnullable
platformPostobjectnullable
The creator's published post this submission is, for a post.
Show 9 child fieldsHide child fields
- idstringnullable
  The post's ID on its platform.
- platformenum
  instagramtiktok
- urlstringnullable
- captionstringnullable
- metricsobject
  Show 5 child fieldsHide child fields
  viewsnumbernullable
  likesnumbernullable
  commentsnumbernullable
  sharesnumbernullable
  savesnumbernullable
- publishedAtstringnullable
- paidViewsnumbernullable
  Views counted toward pay once measurement ends.
- measurementEndsAtstringnullable
- paymentApprovedAtstringnullable
transcriptobjectnullable
Show 3 child fieldsHide child fields
- statusenum
  completedfailedpendingskippedunsupported
- textstringnullable
- segmentsobject[]nullable
  The transcript as timed lines, start and end in seconds from the video's start.
  Show 3 child fieldsHide child fields
  startnumber
  endnumber
  textstring
adsobjectnullable
Show 4 child fieldsHide child fields
- identityenumnullable
  creatorbrand
- launchedOnstring[]
- ownershipstringnullable
- programTypestringnullable
existingPostobject
A brand's existing TikTok post to boost (added with post): no upload, it runs as itself. Absent for an uploaded video.
Show 4 child fieldsHide child fields
- connectionconn_…
  The TikTok ad connection it runs on.
- handlestringnullable
- readyboolean
  Authorized to the advertiser, so campaigns can run it; false while waiting on the creator's Spark code, or once it expires.
- authorizedUntilstringnullable
adAuthorizationobjectnullable
The newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
- idadauth_…
- platformenum
  metatiktok
- statusenum
  requestedgrantedrevokedexpired
- authorizedAtstringnullable
- expiresAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/submissions/:id

As creatorread

Get a submission

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

Path parameters

idsub_…· required

Response20019 fieldsShow

idsub_…
typeenum
post: the creator's published Instagram or TikTok post; video: an uploaded video.
videopost
programprog_…nullable
creatorcrtr_…nullable
revisionOfsub_…nullable
statusenum
A 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_requestedapprovedliverejectedmeasuringwithdrawnarchived
feedbackstringnullable
The brand's note with its latest review, such as what to change in a revision.
shortIdstringnullable
The short ID shown in the app and ad names.
submittedAtstringnullable
tagsstring[]
mediaobjectnullable
Show 6 child fieldsHide child fields
- videoUrlstringnullable
- thumbnailUrlstringnullable
- durationSecondsnumbernullable
- fileNamestringnullable
- sizenumbernullable
- contentTypestringnullable
platformPostobjectnullable
The creator's published post this submission is, for a post.
Show 9 child fieldsHide child fields
- idstringnullable
  The post's ID on its platform.
- platformenum
  instagramtiktok
- urlstringnullable
- captionstringnullable
- metricsobject
  Show 5 child fieldsHide child fields
  viewsnumbernullable
  likesnumbernullable
  commentsnumbernullable
  sharesnumbernullable
  savesnumbernullable
- publishedAtstringnullable
- paidViewsnumbernullable
  Views counted toward pay once measurement ends.
- measurementEndsAtstringnullable
- paymentApprovedAtstringnullable
transcriptobjectnullable
Show 3 child fieldsHide child fields
- statusenum
  completedfailedpendingskippedunsupported
- textstringnullable
- segmentsobject[]nullable
  The transcript as timed lines, start and end in seconds from the video's start.
  Show 3 child fieldsHide child fields
  startnumber
  endnumber
  textstring
adsobjectnullable
Show 4 child fieldsHide child fields
- identityenumnullable
  creatorbrand
- launchedOnstring[]
- ownershipstringnullable
- programTypestringnullable
existingPostobject
A brand's existing TikTok post to boost (added with post): no upload, it runs as itself. Absent for an uploaded video.
Show 4 child fieldsHide child fields
- connectionconn_…
  The TikTok ad connection it runs on.
- handlestringnullable
- readyboolean
  Authorized to the advertiser, so campaigns can run it; false while waiting on the creator's Spark code, or once it expires.
- authorizedUntilstringnullable
adAuthorizationobjectnullable
The newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
- idadauth_…
- platformenum
  metatiktok
- statusenum
  requestedgrantedrevokedexpired
- authorizedAtstringnullable
- expiresAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

POST/v1/submissions

As creatorwrite

Submit work as a creator, or add a brand's own video, or an existing TikTok post to boost, to its library

const { data } = await lucra.submissions.create({
  body: { program: "prog_…" },
})

Body

programprog_…
The program the work is for; required for a creator.
filefile_…
The uploaded video; required unless post is sent.
notestring
postobject
As a brand: an existing TikTok post to run as a Spark Ad, by its creator's Spark code, its link, or both.
Show 3 child fieldsHide child fields
- connectionconn_…· required
  The brand's TikTok ad connection that will run the post.
- urlstring
  The post's full link, like https://www.tiktok.com/@handle/video/7234…
- sparkCodestring
  The creator's Spark code for the post; without one, Lucra asks the creator.
postUrlstring
The URL of the creator's published Instagram or TikTok post this video is; organic programs pay on its views.
revisionOfsub_…
attestationobject
The creator's content-compliance confirmations.
Show 4 child fieldsHide child fields
- disclosureIncludedboolean· required
- experienceTruthfulboolean· required
- noUnapprovedClaimsboolean· required
- acceptedAgreementsobject[]
  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_…· required
  versioninteger· required
namestring
A brand library video's title; defaults to its file name.

Response20119 fieldsShow

idsub_…
typeenum
post: the creator's published Instagram or TikTok post; video: an uploaded video.
videopost
programprog_…nullable
creatorcrtr_…nullable
revisionOfsub_…nullable
statusenum
A 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_requestedapprovedliverejectedmeasuringwithdrawnarchived
feedbackstringnullable
The brand's note with its latest review, such as what to change in a revision.
shortIdstringnullable
The short ID shown in the app and ad names.
submittedAtstringnullable
tagsstring[]
mediaobjectnullable
Show 6 child fieldsHide child fields
- videoUrlstringnullable
- thumbnailUrlstringnullable
- durationSecondsnumbernullable
- fileNamestringnullable
- sizenumbernullable
- contentTypestringnullable
platformPostobjectnullable
The creator's published post this submission is, for a post.
Show 9 child fieldsHide child fields
- idstringnullable
  The post's ID on its platform.
- platformenum
  instagramtiktok
- urlstringnullable
- captionstringnullable
- metricsobject
  Show 5 child fieldsHide child fields
  viewsnumbernullable
  likesnumbernullable
  commentsnumbernullable
  sharesnumbernullable
  savesnumbernullable
- publishedAtstringnullable
- paidViewsnumbernullable
  Views counted toward pay once measurement ends.
- measurementEndsAtstringnullable
- paymentApprovedAtstringnullable
transcriptobjectnullable
Show 3 child fieldsHide child fields
- statusenum
  completedfailedpendingskippedunsupported
- textstringnullable
- segmentsobject[]nullable
  The transcript as timed lines, start and end in seconds from the video's start.
  Show 3 child fieldsHide child fields
  startnumber
  endnumber
  textstring
adsobjectnullable
Show 4 child fieldsHide child fields
- identityenumnullable
  creatorbrand
- launchedOnstring[]
- ownershipstringnullable
- programTypestringnullable
existingPostobject
A brand's existing TikTok post to boost (added with post): no upload, it runs as itself. Absent for an uploaded video.
Show 4 child fieldsHide child fields
- connectionconn_…
  The TikTok ad connection it runs on.
- handlestringnullable
- readyboolean
  Authorized to the advertiser, so campaigns can run it; false while waiting on the creator's Spark code, or once it expires.
- authorizedUntilstringnullable
adAuthorizationobjectnullable
The newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
- idadauth_…
- platformenum
  metatiktok
- statusenum
  requestedgrantedrevokedexpired
- authorizedAtstringnullable
- expiresAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

PATCH/v1/submissions/:id

As creatorwrite

Review, tag, file or archive a submission, or approve paying for a post; as its creator, withdraw it

const { data } = await lucra.submissions.update({
  path: { id: "sub_…" },
  body: { status: "pending" },
})

Path parameters

idsub_…· required

Body

statusenum
A post in an organic program is approved (paid on its measured views) or rejected; archived hides a rejected or withdrawn submission from lists (it stays readable, and lists with status=archived); a creator sends withdrawn. Any member may approve, reject or request a revision (with a note); other changes need an owner or admin.
pendingapprovedrejectedrevision_requestedwithdrawnarchived
notestring
Shown to the creator with a revision request or rejection.
tagsstring[]
paymentstring
For an approved post: approves paying the creator its finalized earnings (the brand's owner, admin or own key).
approved
versioninteger

Response20019 fieldsShow

idsub_…
typeenum
post: the creator's published Instagram or TikTok post; video: an uploaded video.
videopost
programprog_…nullable
creatorcrtr_…nullable
revisionOfsub_…nullable
statusenum
A 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_requestedapprovedliverejectedmeasuringwithdrawnarchived
feedbackstringnullable
The brand's note with its latest review, such as what to change in a revision.
shortIdstringnullable
The short ID shown in the app and ad names.
submittedAtstringnullable
tagsstring[]
mediaobjectnullable
Show 6 child fieldsHide child fields
- videoUrlstringnullable
- thumbnailUrlstringnullable
- durationSecondsnumbernullable
- fileNamestringnullable
- sizenumbernullable
- contentTypestringnullable
platformPostobjectnullable
The creator's published post this submission is, for a post.
Show 9 child fieldsHide child fields
- idstringnullable
  The post's ID on its platform.
- platformenum
  instagramtiktok
- urlstringnullable
- captionstringnullable
- metricsobject
  Show 5 child fieldsHide child fields
  viewsnumbernullable
  likesnumbernullable
  commentsnumbernullable
  sharesnumbernullable
  savesnumbernullable
- publishedAtstringnullable
- paidViewsnumbernullable
  Views counted toward pay once measurement ends.
- measurementEndsAtstringnullable
- paymentApprovedAtstringnullable
transcriptobjectnullable
Show 3 child fieldsHide child fields
- statusenum
  completedfailedpendingskippedunsupported
- textstringnullable
- segmentsobject[]nullable
  The transcript as timed lines, start and end in seconds from the video's start.
  Show 3 child fieldsHide child fields
  startnumber
  endnumber
  textstring
adsobjectnullable
Show 4 child fieldsHide child fields
- identityenumnullable
  creatorbrand
- launchedOnstring[]
- ownershipstringnullable
- programTypestringnullable
existingPostobject
A brand's existing TikTok post to boost (added with post): no upload, it runs as itself. Absent for an uploaded video.
Show 4 child fieldsHide child fields
- connectionconn_…
  The TikTok ad connection it runs on.
- handlestringnullable
- readyboolean
  Authorized to the advertiser, so campaigns can run it; false while waiting on the creator's Spark code, or once it expires.
- authorizedUntilstringnullable
adAuthorizationobjectnullable
The newest ad authorization asked for it (GET /v1/ad-authorizations).
Show 5 child fieldsHide child fields
- idadauth_…
- platformenum
  metatiktok
- statusenum
  requestedgrantedrevokedexpired
- authorizedAtstringnullable
- expiresAtstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring