Build a Creator Search App

Turn a campaign brief into a shortlist with a server-side API call, match explanations, and CSV export. The example uses Next.js, TypeScript, and the published Influship SDK. If you want to make a single request first, follow the quickstart. For a different workflow, browse the cookbook.

Run the example

Download the complete MIT-licensed source or clone the public example repository. The archive includes the app, lockfile, example environment file, and tests. You need Node.js 22+ and pnpm 10.32.1.

unzip creator-shortlist.zip
cd creator-shortlist
pnpm install --frozen-lockfile
cp .env.example .env.local

Set INFLUSHIP_API_KEY in .env.local using a key from the developer dashboard, then start the app:

pnpm dev

Open http://localhost:3000, describe your campaign, and submit the form. The app displays up to five creators. Exporting a CSV reuses those results without another API call. For the use-case explanation and a captioned walkthrough of a real API run, read the build guide.

Find the code

File	Responsibility
`app/page.tsx`	Brief form, results, error states, and CSV download
`app/api/search/route.ts`	Server-side SDK call, input validation, and API error mapping
`lib/shortlist.ts`	Response mapping, unknown metrics, and CSV serialization
`lib/shortlist.test.ts`	Synthetic checks for input bounds, origin checks, mapping, and CSV safety

Start with the route handler when integrating search into an existing app. Reuse the mapping and CSV helpers if you already have a results UI. The SDK guide covers client setup and error classes; the API reference defines request and response fields.

This example runs on your local machine. Add your application’s authentication and per-user request and spending limits before hosting the search endpoint. The API key stays on the server.

The server-side search

The core request is:

import Influship from 'influship';

const client = new Influship({ maxRetries: 0, timeout: 60_000 });
const { data, response } = await client.search.create({
  query: 'Fitness creators who teach home workouts with minimal equipment',
  platforms: ['instagram'],
  limit: 5,
}).withResponse();

console.log(data.data);
console.log(response.headers.get('x-credits-charged'));

The server validates the brief before making a request. query accepts at most 500 characters. This example requires at least three characters and disables automatic retries so one submission does not silently repeat a search. The browser submits the brief to the app’s /api/search route. That route reads INFLUSHIP_API_KEY, calls Influship, and returns only the fields the UI needs. Never put the key in a NEXT_PUBLIC_ variable.

What the app displays

Field	Display behavior
`creator.name`	Creator display name
`relevant_profile ?? primary_profile`	Instagram handle and available metrics
`match.score`	Relevance to the search query
`match.reasons`	Plain-text explanations
`match.ranking_source`	Distinguishes reranked results from retrieval fallback
`match.low_confidence`	Flags results that need closer review
`location_unverified`	Flags a location requirement that needs verification
`X-Credits-Charged`	Actual credits charged for the successful request

An illustrative card using synthetic example data looks like this:

Alex Example · @alex_example
Search relevance: 87%
42,000 followers · 3.1% engagement
Reason: Creates approachable home workout tutorials.

Missing follower and engagement metrics display as unknown, not zero. Retrieval fallback scores are labeled as retrieval relevance. Neither kind of score predicts conversions, sales, or campaign ROI. See Match Reasons.

Errors and empty results

The app handles loading, empty results, missing server configuration, invalid keys, insufficient credits, permission failures, rate limits, and temporary failures. It preserves Retry-After when the API supplies it and waits for a new user submission rather than retrying automatically. An empty response is a completed search with no candidates. Broaden the brief or remove constraints before submitting again. See Error Handling for API recovery rules.

Cost and verification

A search returning five creators costs 35 credits ($0.35): 25 credits per search plus two per delivered creator. Returning fewer creators costs less. CSV export costs nothing. See Pricing.

pnpm type-check
pnpm test
pnpm build

The tests use synthetic records and make no API requests. Submit a brief with your own key to verify live access and review the actual results.

Troubleshoot setup

Symptom	Next step
Missing `INFLUSHIP_API_KEY`	Set the key in `.env.local` and restart the app. Get a key from the developer dashboard.
Invalid key or permission error	Check the key and its access in the dashboard. See Authentication.
Insufficient credits	Check your balance and request costs before submitting again.
Rate limit or temporary failure	Follow the error recovery rules and respect `Retry-After`.
No candidates	Broaden the brief. See How Search Works for query guidance.

For an API issue, contact support with the endpoint, status, and request ID when available. Keep the API key out of your report.

Extend the app

Build a Creator Shortlist adds campaign scoring and profile expansion.
Compare Creators for a Campaign scores creators you already know.
Expand a Roster with Lookalikes finds creators similar to an existing roster.
Export a Shortlist to CSV adds a standalone export script.

Getting Started

Concepts

Guides

Cookbook

Billing & Limits

Integrations

Updates

Build a Creator Search App

Run the example

Find the code

The server-side search

What the app displays

Errors and empty results

Cost and verification

Troubleshoot setup

Extend the app

​Run the example

​Find the code

​The server-side search

​What the app displays

​Errors and empty results

​Cost and verification

​Troubleshoot setup

​Extend the app

Run the example

Find the code

The server-side search

What the app displays

Errors and empty results

Cost and verification

Troubleshoot setup

Extend the app