> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```typescript theme={null}
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 <Tooltip tip="Credits are the billing unit for API usage. 1 credit = \$0.01.">credits</Tooltip> 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.

```typescript theme={null}
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 <Tooltip tip="Match decisions are AI-generated verdicts: good (strong fit), neutral (review manually), or avoid (weak fit).">decision</Tooltip> (`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:

```typescript theme={null}
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:

```typescript theme={null}
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.