How to Build an Influencer Discovery Tool (with Code)

A useful first discovery tool has a small job: take a campaign brief, return creators worth reviewing, and let someone export the result. You can build that with one API request. Add campaign scoring once you know what your team needs to judge.

We've published a complete Next.js starter for that first job. It uses the Influship TypeScript SDK, keeps the API key on the server, shows relevance scores and reasons, and exports a CSV. The source is MIT licensed and includes its lockfile, setup instructions and tests. The maintained recipe is the place to follow the implementation as it changes.

What the app does

Enter a brief such as “Fitness creators who teach approachable home workouts with minimal equipment.” The server requests up to five Instagram creators. Each card shows a handle, available profile metrics, relevance to the search and the reasons behind it. The app also shows the credits charged for that request.

Watch the walkthrough

Run it locally

You need Node.js 22+, pnpm 10.32.1 and an API key from the developer dashboard. Check your balance before making a request. Download the standalone source ZIP or clone the public repository:

git clone https://github.com/Influship/influship-examples.git
cd influship-examples/creator-shortlist
pnpm install --frozen-lockfile
cp .env.example .env.local

Set INFLUSHIP_API_KEY in .env.local, then run pnpm dev and open http://localhost:3000. Never give this variable a NEXT_PUBLIC_ prefix: the browser should receive results, not your credential.

Submit the default brief, review the cards and choose Export CSV. Export uses the result already in the browser, so it makes no extra API request. The setup guide includes the file map, expected states and recovery steps if the key, balance or request fails.

The request behind the form

The route handler calls the published client with a bounded result count. This excerpt shows the API call; validation and error handling live in the complete starter.

import Influship from 'influship';

const client = new Influship({ maxRetries: 0, timeout: 60_000 });
const { data, response } = await client.search.create({
  query: brief,
  platforms: ['instagram'],
  limit: 5,
}).withResponse();

const creditsCharged = response.headers.get('x-credits-charged');

At five delivered results, this costs 35 credits ($0.35): a 25-credit search base and two credits per result. Fewer delivered results cost less. The app disables automatic SDK retries so it does not silently repeat a billable search. Read pricing and error recovery before choosing a retry policy for your own application.

What a relevance score can tell you

Search relevance describes how well a creator matches the query. It does not predict sales or campaign performance. The starter keeps missing metrics blank, displays retrieval fallbacks and uncertainty when supplied, and preserves location warnings. A missing metric should not become a zero just because zero is easier to put in a table.

When you need a separate judgement against a campaign brief, use creators.match. That response includes a campaign-fit score, a good/neutral/avoid decision and structured reasons. Keep those signals distinct from the original search score. The shortlist workflow demonstrates the full sequence: search up to ten creators, score the returned candidates, exclude avoid decisions and expand up to three profiles. Its maximum is five requests and 55.3 credits ($0.553).

Choose the next workflow

• Already have handles? Compare known creators directly against a brief, or resolve an existing list and score the creators behind it. For a full spreadsheet with emails, follow the list enricher build guide.
• Have a roster you like? Expand it with lookalikes and score those candidates separately for your campaign.
• Need a file instead of an app? Use the CSV script.

The recipe hub lists the runnable source, prerequisites, call budgets and related guides for each path. The CLI workflows are also in the public repository.

Before you host it

This starter runs locally. For a shared app, add authentication, per-user request and spending limits, and an origin check appropriate to your deployment. Store results you need to revisit rather than paying for another search just to display yesterday's shortlist. Keep your key out of client code, logs and exports.

The repository's synthetic tests verify response mapping, unknown values, CSV safety and request boundaries. They do not prove live account access or creator quality. We also ran the app and all three CLI workflows against a dedicated account with normal credit charging. That check did not exercise a new customer's signup or card flow.

If you're building an agent, start with the same bounded workflow and explicit budget. See the agent integration overview and the API reference. Keep outreach and other consequential actions behind the approval rules your product needs.