Build a Creator Shortlist

Build a reviewable shortlist by discovering candidates, scoring them against a campaign brief, and expanding up to three creator records. This recipe uses at most five API requests and 55.3 credits ($0.553) when every stage reaches its limit. For a browser app with CSV export, start with Build a Creator Search App. This workflow adds campaign scoring and creator expansion.

Run the complete program

Download the MIT-licensed workflow source or browse it on GitHub. Requires Node.js 22+, pnpm 10.32.1, and an API key.

unzip cookbook-workflows.zip
cd workflows
pnpm install --frozen-lockfile
export INFLUSHIP_API_KEY="your_api_key_here"
pnpm shortlist "Fitness creators teaching approachable home workouts"

The quickstart covers key setup. Keep the key in your environment. The source uses the TypeScript SDK; workflows.ts contains the API stages and cli.ts handles command-line output and failures.

The three stages

Search Instagram with limit: 10 and your brief.
Match the distinct returned creator IDs against the same brief.
Expand up to three non-avoid results, ordered by campaign score, with include: ['profiles'].

An excerpt of the first call is:

const { data: search, response } = await client.search.create({
  query: brief,
  platforms: ['instagram'],
  limit: 10,
}).withResponse();

The full program validates a 3–500 character brief before making requests. An empty search stops before matching. Empty or entirely avoid match results stop before expansion. Duplicate creator IDs are scored only once. Expansion requests run sequentially, and automatic SDK retries are disabled. neutral results remain available for manual review. Search relevance and campaign fit describe different questions; keep both rather than combining them into an unexplained score. See Match Reasons.

Read the output

This abbreviated output uses synthetic example data:

{
  "searchId": "123e4567-e89b-12d3-a456-426614174000",
  "candidates": [{
    "search": {
      "creator": { "name": "Alex Example" },
      "primary_profile": null,
      "match": { "score": 0.4, "ranking_source": "retrieval_fallback", "low_confidence": true },
      "location_unverified": true
    },
    "campaign": {
      "decision": "neutral", "score": 0.8,
      "reasons": [{ "text": "Review the campaign alignment", "provenance": "inferred" }]
    },
    "creator": { "name": "Alex Example", "profiles": [] },
    "warning": null
  }],
  "usage": [{ "stage": "search", "credits": "27" }, { "stage": "campaign match", "credits": "1" }, { "stage": "creator expansion", "credits": "0.1" }],
  "creditsCharged": "28.10"
}

The full search record retains explanations, ranking source, confidence, and location verification. Campaign reasons retain structured provenance and supporting evidence. Creator-expansion warnings remain visible. Unknown metrics remain unknown. No score predicts sales or campaign ROI.

Maximum intended cost

Stage	Limit	Credits
Search	10 delivered creators	45
Campaign match	10 distinct creators	10
Creator expansion	3 records	0.3
Maximum total	5 requests	55.3 ($0.553)

Fewer results or expansions reduce the total. Actual usage comes from each response’s X-Credits-Charged header; missing headers produce an unknown total. See Pricing.

Verification and recovery

pnpm type-check
pnpm test

The tests use the published SDK with synthetic HTTP responses. They verify stage boundaries and failure behavior without calling the API. Run a budgeted live command with your own key and review its returned creators separately. A failure ends the program. The CLI reports the status, request ID and Retry-After when supplied; it does not silently repeat a billable stage. Follow Error Handling before running it again. Re-running the command starts a new search.

Save the reviewed selection

Select one to eight distinct Instagram profiles and follow Save a Shortlist to keep their usernames, your brief, and review notes. Saved lists cost no credits and are shared by API keys under the same account. Use the creator research app for a complete selection and save interface.

Compare Creators scores handles directly when you already have candidates.
Expand with Lookalikes starts from an existing roster.
Export a Shortlist to CSV exports a single search without expansion.
Browse the cookbook for other workflows. Contact support with the endpoint, status, and request ID; keep keys out of your report.

Start building

Find and evaluate creators

Research and save

Apps and workflows

Live platform data

Connect your tools

Operate your integration

Build a Creator Shortlist

Run the complete program

The three stages

Read the output

Maximum intended cost

Verification and recovery

Save the reviewed selection

​Run the complete program

​The three stages

​Read the output

​Maximum intended cost

​Verification and recovery

​Save the reviewed selection

​Related recipes

Run the complete program

The three stages

Read the output

Maximum intended cost

Verification and recovery

Save the reviewed selection

Related recipes