Campaigns

Create with a goalCopy Anchor Link

curl -X POST "https://www.starcovery.com/api/campaigns" \
  -H "x-api-key: <access_token>" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coffee",
    "goal": "quiet morning coffee creators who film at home"
  }'

You can include contract, embargoUntil (campaign details declassifying date), disclosure, and marketInformation on create. contract takes compensationCents, deliverable, platforms, the platforms one payment covers (["ig"], ["tt"], or ["ig", "tt"]), and the optional creator posting date in creatorPostingDate; a hired creator posts on each platform they run. embargoUntil needs contract in the same body, or the create returns 400 invalid_campaign_terms with the reason in message.

marketInformation is {"releaseDelayMonths": <n>}, the answer that decides when the campaign's name and pay per creator join the going rate, the list of campaigns and the typical pay other organizations and creators see, and that sets the platform fee. The going rate shows nothing about the organization that ran the campaign, and a campaign joins it no earlier than its declassifying date. Omit marketInformation to leave the question unanswered; on create, "marketInformation": null returns 400 invalid_body. Funding requires an answer. releaseDelayMonths takes one of these values:

• 0 adds them once funding is requested, with no platform fee.
• 1 to 18 holds them back that many months after the first funding request, for a fee of that many percent of the creator pool.
• null keeps them out, for a 20% fee.

To retry a create safely, send the same idempotencyKey (1 to 128 characters) and a complete, valid body on each attempt. A repeat with a key your organization already used returns the campaign the first request created, even when the rest of the body differs, and charges nothing.

On create and update, a contract or date that fails the terms check returns 400 invalid_campaign_terms with the reason in message.

Generate matchesCopy Anchor Link

curl -X POST "https://www.starcovery.com/api/campaigns/{campaignId}/generate" \
  -H "x-api-key: <access_token>" \
  -H "content-type: application/json" \
  -d '{}'

Generation runs one creator search against the campaign goal, billed like GET /api/search, and stores the ranked creators on the campaign.

Add or remove matchesCopy Anchor Link

Add or remove individual matches with POST /api/campaigns/{campaignId}/matches and DELETE /api/campaigns/{campaignId}/matches/{matchId}. Removing a match that already has a proposal delivery returns 409 campaign_match_delivered.

Read, update, or exportCopy Anchor Link

Read the campaign with matches (GET /api/campaigns/{campaignId}), update it (PATCH /api/campaigns/{campaignId}), or export the shortlist as CSV (GET /api/campaigns/{campaignId}/export).

GET /api/campaigns and GET /api/campaigns/{campaignId} carry nextStep, the step the web app shows next on the campaign:

{
  "id": "fund",
  "label": "Fund the creators who accepted",
  "actor": "you",
  "line": "2 creators accepted. Fund $600 to lock them in."
}

For members of the organization, GET /api/campaigns/{campaignId} also carries people, each person on the campaign with their answer, funding, and signed hire. A hire lists posts, each live post Starcovery recorded, one per platform, with its url, viewCount, engagementCount (likes plus comments), and recordedAt.

id is one of pick, proposal, send, answers, fund, post, and payout, in campaign order. actor names who takes the step: you for your organization, starcovery, creators, or {"creator": "<name>"} when one funded creator has yet to post. nextStep is null once no step is left, because the campaign is done or archived or no creator was reached or accepted, and on a campaign another organization owns.

GET /api/campaigns/{campaignId} also carries currentSteps, every step under way in campaign order, in the same shape. A step before nextStep can still wait: while Starcovery has not sent every proposal and a later step waits too, nextStep names the later step and currentSteps lists the send step before it. currentSteps is empty once no step is left and null on a campaign another organization owns.

Update name, goal, visibility, status, contract, campaign details declassifying date (embargoUntil), creator posting date (contract.creatorPostingDate), disclosure, or marketInformation (null clears it). contract replaces the stored contract: send compensationCents, deliverable, and platforms with it, and send creatorPostingDate again to keep the posting date. Status takes draft or archived; Starcovery sets active when the team sends the proposals. A campaign that is active or holds a proposal delivery cannot return to draft, and a campaign with a send or funding request open with the Starcovery team cannot be archived; either patch returns 409 campaign_status_locked with reason sent or request_open. The contract locks when the team sends the proposals: while the campaign is active or holds a proposal delivery, a patch that changes or clears contract returns 409 contract_locked.

curl -X PATCH "https://www.starcovery.com/api/campaigns/{campaignId}" \
  -H "x-api-key: <access_token>" \
  -H "content-type: application/json" \
  -d '{
    "goal": "quiet morning coffee creators who film at home"
  }'

Omit a top-level field you do not want to change.