Build a Creator Shortlist

Search for creators, score them against a campaign brief, and build a ranked shortlist

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. It has three billable API stages and makes up to 12 requests when you expand ten creators.

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.search.create({
  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. When the search returns all 30 results, the 25 base + (30 x 2) per-creator credits costs 85 credits ($0.85). Searches that return fewer results cost less.

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({
  creators: creatorIds.map((creator_id) => ({ creator_id })),
  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 decision (good, neutral, or avoid) and a numeric score. At 1 credit per creator scored, this adds up to 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.data.name);
  for (const profile of creator.data.profiles ?? []) {
    console.log(`  ${profile.platform}: @${profile.username} (${profile.followers} followers)`);
  }
}

At 0.1 credits per lookup, 10 lookups add 1 credit ($0.01).

Maximum Cost

This maximum assumes the search returns 30 creators, all 30 are scored, and ten creator records are expanded. Fewer returned or expanded creators reduce the total.

Step	Endpoint	Credits	Cost
Search (30 results)	POST /v1/search	85	$0.85
Score (30 creators)	POST /v1/creators/match	30	$0.30
Expand (10 creators)	GET /v1/creators/{id}	1	$0.01
Maximum total		116	$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.