> ## 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 Search App

> Run a Next.js app that turns a campaign brief into an Instagram creator shortlist

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](/sdks).

If you want to make a single request first, follow the [quickstart](/quickstart). For a different workflow, browse the [cookbook](/cookbook).

## Run the example

[Download the complete MIT-licensed source](https://github.com/Influship/influship-examples/releases/download/v1.0.0/creator-shortlist.zip) or [clone the public example repository](https://github.com/Influship/influship-examples/tree/main/creator-shortlist). The archive includes the app, lockfile, example environment file, and tests. You need Node.js 22+ and pnpm 10.32.1. The ZIP path also needs an extraction tool such as `unzip`; use the Git clone alternative below if your environment does not include one.

```bash theme={null}
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](https://developers.influship.com), then start the app:

```bash theme={null}
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](https://www.influship.com/blog/build-influencer-discovery-tool#watch-the-walkthrough).

## Clone instead of downloading

If you prefer Git or do not have `unzip`, use the same source from the public repository:

```bash theme={null}
git clone https://github.com/Influship/influship-examples.git
cd influship-examples/creator-shortlist
pnpm install --frozen-lockfile
cp .env.example .env.local
```

Set your key in `.env.local` and run `pnpm dev` as above.

## 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](/sdks) covers client setup and error classes; the [API reference](/api-reference) defines request and response fields.

<Note>
  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.
</Note>

## The server-side search

The core request is:

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

```text theme={null}
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](/concepts/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](/guides/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](/concepts/pricing).

```bash theme={null}
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](https://developers.influship.com). |
| Invalid key or permission error | Check the key and its access in the dashboard. See [Authentication](/guides/authentication). |
| Insufficient credits | Check your balance and [request costs](/concepts/pricing) before submitting again. |
| Rate limit or temporary failure | Follow the [error recovery rules](/guides/error-handling) and respect `Retry-After`. |
| No candidates | Broaden the brief. See [How Search Works](/concepts/semantic-search) for query guidance. |

For an API issue, contact [support](mailto:elliot@influship.com) with the endpoint, status, and request ID when available. Keep the API key out of your report.

## Extend the app

* [Build a Creator Shortlist](/cookbook/build-a-shortlist) adds campaign scoring and profile expansion.
* [Compare Creators for a Campaign](/cookbook/compare-creators) scores creators you already know.
* [Expand a Roster with Lookalikes](/concepts/lookalikes) finds creators similar to an existing roster.
* [Export a Shortlist to CSV](/cookbook/export-shortlist-csv) adds a standalone export script.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.