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

# Score Campaign Fit for an Existing List

> Take a list of creator handles, resolve them, and score each one against a campaign brief

# Score Campaign Fit for an Existing List

You already have a list of creators — maybe from a spreadsheet, a CRM export, or a previous campaign. You want to evaluate how well each one fits a specific campaign brief. This recipe resolves social handles to creator IDs, then scores them all at once.

## The Flow

1. **Batch lookup** your creator handles to get IDs
2. **Score** them against your campaign brief
3. **Sort** by fit and build your final list

## Step 1: Resolve Handles to Creator IDs

If you're starting from Instagram usernames, batch lookup resolves them in a single request:

```typescript theme={null}
import Influship from 'influship';

const client = new Influship();

// Your existing creator list — from a spreadsheet, CRM, wherever
const handles = [
  { platform: 'instagram' as const, username: 'clean_eating_co' },
  { platform: 'instagram' as const, username: 'mealprep_marcus' },
  { platform: 'instagram' as const, username: 'plantbased_priya' },
  { platform: 'instagram' as const, username: 'fit_kitchen_lee' },
  { platform: 'instagram' as const, username: 'wholesome_hannah' },
  { platform: 'instagram' as const, username: 'nutrition_nate' },
  { platform: 'instagram' as const, username: 'vegan_chef_rio' },
  { platform: 'instagram' as const, username: 'healthy_habits_jo' },
];

const lookup = await client.profiles.lookup({
  profiles: handles,
});

// Some handles may not be in the system — check what resolved
const resolved = lookup.data.filter((p) => p.creator_id);
const missing = handles.length - resolved.length;

if (missing > 0) {
  console.log(`${missing} handle(s) not found in the system — skipping`);
}

console.log(`Resolved ${resolved.length} of ${handles.length} handles`);
```

At 0.1 <Tooltip tip="Credits are the billing unit for API usage. 1 credit = \$0.01.">credits</Tooltip> per profile found, eight resolved profiles cost 0.8 credits (\$0.008). Missing profiles are not charged.

## Step 2: Score Against Campaign Brief

Pass the resolved creator IDs to the match endpoint. The more detail you put in the brief, the more accurate the scoring.

```typescript theme={null}
const creatorIds = [...new Set(resolved.flatMap((p) => (p.creator_id ? [p.creator_id] : [])))];

const scored = await client.creators.match({
  creators: creatorIds.map((creator_id) => ({ creator_id })),
  intent: {
    query: 'Launch campaign for an organic meal delivery service',
    context:
      'Brand targets busy professionals aged 28-40 who want healthy meals ' +
      'without the prep time. Looking for creators who feel authentic and ' +
      'relatable — not aspirational fitness models. Must be comfortable ' +
      'with recipe-style content and unboxing formats. Budget per creator ' +
      'is \$2,000-\$5,000 for a 3-post series.',
  },
});
```

The `context` field accepts up to 2,000 characters. Use it for details that don't fit in the main query — target demographics, content format preferences, budget range, brand tone. The scoring model reads all of it.

## Step 3: Sort and Review

```typescript theme={null}
// Group by decision
const good = scored.data.filter((r) => r.match.decision === 'good');
const neutral = scored.data.filter((r) => r.match.decision === 'neutral');
const avoid = scored.data.filter((r) => r.match.decision === 'avoid');

console.log(`Good fit: ${good.length} | Review: ${neutral.length} | Weak fit: ${avoid.length}`);

// Rank the good fits
const ranked = good.sort((a, b) => b.match.score - a.match.score);

for (const item of ranked) {
  const handle = resolved.find((p) => p.creator_id === item.creator.id);
  console.log(
    `@${handle?.username} — score: ${item.match.score} (${item.match.decision})`,
  );
  for (const reason of item.match.reasons) {
    console.log(`  ${reason.text}`);
  }
}
```

## What the Decisions Mean

| Decision  | What it tells you                                                                |
| --------- | -------------------------------------------------------------------------------- |
| `good`    | Strong fit. The creator's content, audience, and style align with the brief.     |
| `neutral` | Could work, but there are trade-offs. Worth a manual review.                     |
| `avoid`   | Weak fit. The reasons will explain why — usually a content or audience mismatch. |

Don't automatically reject `neutral` creators. Read the reasons — sometimes a creator scores `neutral` because they're slightly outside the follower range you implied in the brief, but their content is an excellent match.

## Total Cost

| Step                       | Endpoint                   | Credits |        Cost |
| -------------------------- | -------------------------- | ------: | ----------: |
| Batch lookup (8 handles)   | `POST /v1/profiles/lookup` |     0.8 |     \$0.008 |
| Match scoring (8 creators) | `POST /v1/creators/match`  |       8 |      \$0.08 |
| **Total**                  |                            | **8.8** | **\$0.088** |

Scoring an existing list is cheap. The expensive part of the API is search — if you already have the list, you skip that cost entirely.

## Tips

* **Write the brief like you'd brief an agency.** Include brand values, target audience, content formats, budget range, and what you're trying to avoid. Vague briefs produce vague scores.
* **Don't filter on score alone.** The reasons are often more useful than the number. A creator scoring 0.78 with the right reasons may be a better choice than one scoring 0.85 with generic reasons.
* **Re-score for different campaigns.** The same creator can score `good` for one brief and `avoid` for another. Campaign fit is relative to the brief, not absolute.
* **Batch lookup handles missing profiles.** If some handles aren't in the system, those creators may not be in the Influship index yet. Reach out to support if you need specific creators added.