Skip to main content

​
Build a Creator Shortlist

This recipe combines search, profile expansion, and campaign match scoring to produce a ranked shortlist of creators for a specific campaign. Three API calls, and you have a shortlist with fit scores and reasoning.

​
The Flow

  1. Search for creators matching your criteria
  2. Score the candidates against your campaign brief
  3. Expand the top picks with full profile data

​
Step 1: Search for Candidates

Start broad. Search returns creators ranked by relevance to your query, so you want a large enough pool to filter down from. 
import Influship from 'influship';

const client = new Influship();

const search = await client.creators.search({
  query: 'health and wellness creators who make educational content about nutrition',
  platforms: ['instagram'],
  filters: {
    followers: { min: 25000, max: 500000 },
    engagement_rate: { min: 2.0 },
  },
  limit: 30,
});

console.log(`Found ${search.data.length} candidates`);
A limit of 30 gives you a good candidate pool. At 25 base + (30 x 2) per-creator , this costs 85 credits ($0.85).

​
Step 2: Score Against Your Campaign Brief

Pass the candidate IDs to the match endpoint with your campaign details. The query field (up to 500 chars) describes the campaign, and context (up to 2,000 chars) adds background. 
const creatorIds = search.data.map((r) => r.creator.id);

const scored = await client.creators.match({
  creator_ids: creatorIds,
  intent: {
    query: 'Promote a new line of plant-based protein supplements',
    context:
      'Brand is targeting health-conscious millennials aged 25-35. ' +
      'Looking for creators who can make authentic educational content, ' +
      'not just product placements. Budget is mid-range.',
  },
});
Each result comes back with a (good, neutral, or avoid) and a numeric score. At 1 credit per creator scored, this adds 30 credits ($0.30).

​
Step 3: Filter and Rank

Pull out the strong fits and sort by score: 
const shortlist = scored.data
  .filter((r) => r.match.decision === 'good')
  .sort((a, b) => b.match.score - a.match.score);

console.log(`${shortlist.length} creators passed campaign fit scoring`);

for (const item of shortlist.slice(0, 10)) {
  console.log(
    `${item.creator.id} — score: ${item.match.score}, reason: ${item.match.reasons[0]?.text}`
  );
}

​
Step 4: Expand Top Picks

For the creators you’re actually going to pitch, fetch full profiles with linked social accounts: 
const topPicks = await Promise.all(
  shortlist.slice(0, 10).map((item) =>
    client.creators.retrieve(item.creator.id, { include: ['profiles'] })
  ),
);

for (const creator of topPicks) {
  console.log(creator.name);
  for (const profile of creator.profiles ?? []) {
    console.log(`  ${profile.platform}: @${profile.username} (${profile.followers} followers)`);
  }
}
At 0.1 credits per lookup, 10 lookups add 1 credit ($0.01).

​
Total Cost

StepEndpointCreditsCost
Search (30 results)POST /v1/search85$0.85
Score (30 creators)POST /v1/creators/match30$0.30
Expand (10 creators)GET /v1/creators/{id}1$0.01
Total116$1.16

​
Tips

  • Write a detailed campaign brief. The match endpoint uses an LLM to evaluate fit — more context in the query and context fields produces more accurate decisions. Don’t just write “fitness campaign.”
  • Search broad, score narrow. It’s cheaper to over-search and then filter with match scoring than to run multiple targeted searches.
  • Cache creator lookups. If you’re building shortlists frequently for similar campaigns, the creator data doesn’t change often. Cache the Step 4 responses.
  • Iterate on the query. If match scoring flags most candidates as neutral or avoid, your search query may be too broad. Tighten the search, not the scoring threshold.