SDKs

Install the TypeScript SDK and start making API calls in minutes

SDKs

The TypeScript SDK is auto-generated from the OpenAPI spec. It gives you typed methods, request/response models, and automatic error classes — so you spend less time reading docs and more time building.

Install with AI

Copy this prompt into Codex, Claude Code, Cursor, or another coding agent.

Install the Influship SDK using this project's existing conventions.

CopiedCopy promptOpen in Cursor

TypeScript / JavaScript

Installation

npm

npm install influship

yarn

yarn add influship

pnpm

pnpm add influship

bun

bun add influship

Client Setup

import Influship from 'influship';

const client = new Influship({
  apiKey: process.env.INFLUSHIP_API_KEY,
});

If INFLUSHIP_API_KEY is set in your environment, you can skip the config object entirely:

const client = new Influship();

Common Operations

Search

Search accepts a natural language query and returns ranked creators. Describe the kind of creator you need — the API handles the matching.

const results = await client.search.create({
  query: 'sustainable fashion creators',
  limit: 10,
  filters: {
    followers: { min: 10000, max: 500000 },
    engagement_rate: { min: 2.0 },
  },
});

for (const result of results.data) {
  console.log(result.creator.name, result.match.score);
}

Start with a small limit (5-10) while prototyping. Larger limits cost more credits and usually return diminishing-value results past the top 15-20.

Lookalike

Find creators similar to ones you already know. You can weight seeds to influence which traits matter more in the results.

const similar = await client.creators.lookalike({
  seeds: [
    { platform: 'instagram', username: 'fitness_coach_jane', weight: 1.0 },
    { platform: 'instagram', username: 'wellness_daily', weight: 0.5 },
  ],
  limit: 15,
});

A higher weight means the API leans more heavily on that seed’s profile characteristics. Use this when one seed is a better example of what you want than the others.

Campaign Match

Score how well specific creators fit a campaign brief. Each result includes a decision (strong fit, moderate fit, or weak fit) and a numeric score.

const fit = await client.creators.match({
  creators: [
    { creator_id: '123e4567-e89b-12d3-a456-426614174000' },
    { creator_id: '987fcdeb-51a2-43d7-8b90-123456789abc' },
  ],
  intent: {
    query: 'Promote a new plant-based protein bar',
    context: 'Target audience is health-conscious millennials aged 22-35',
  },
});

for (const result of fit.data) {
  console.log(result.match.decision, result.match.score);
}

Profile Lookup

Retrieve a single creator profile by platform and username.

const profile = await client.profiles.get('jamietravels', { platform: 'instagram' });

Batch Lookup

Look up multiple profiles in a single request. This is more efficient than calling profiles.get in a loop — one request, one billing event.

const profiles = await client.profiles.lookup({
  profiles: [
    { platform: 'instagram', username: 'jamietravels' },
    { platform: 'instagram', username: 'chefmarco' },
  ],
});

Profile lookups are cheap but add up at scale. Cache these responses if your use case allows it — creator data doesn’t change often.

Creator Email Lookup

Fetch known email addresses for creators. Identify each creator by Influship creator_id or by platform + username — you can mix both in one request. Response rows preserve the input order.

const emails = await client.creatorEmails.lookup({
  creators: [
    { platform: 'instagram', username: 'jamietravels' },
    { creator_id: '123e4567-e89b-12d3-a456-426614174000' },
  ],
});

Emails can be unvalidated, so check each status before treating an address as deliverable. You’re charged only for resolved creators that return at least one email.

Error Handling

The SDK exports typed error classes so you can handle failures precisely.

import Influship, { APIError, RateLimitError } from 'influship';

try {
  const results = await client.search.create({ query: 'fitness' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Account rate limited, retry after:', error.headers?.get('retry-after'));
  } else if (error instanceof APIError && error.status === 503) {
    console.log('Temporary upstream issue, retry after:', error.headers?.get('retry-after'));
  } else if (error instanceof APIError) {
    console.log('API error:', error.status, error.message);
  }
}

429 rate_limit_exceeded means your API key hit its account-level quota. Live-data requests can return 503 service_unavailable when they cannot be completed. Honor Retry-After when present, use bounded exponential backoff, and add jitter between attempts.

Health and Readiness

GET /health is the unauthenticated process-liveness check. It answers when the API process is running, even if a downstream dependency is temporarily unavailable.

GET /ready is the unauthenticated dependency-readiness check for operators and load balancers. It checks required downstream dependencies in parallel, returning 200 only when every dependency is ready and 503 otherwise. The response exposes status and latency per dependency without credentials or upstream error details.

See Error Handling for the full error reference.

Python

There is no official Python SDK. Use the REST API directly with requests or httpx.

import requests

response = requests.post(
    'https://api.influship.com/v1/search',
    headers={'X-API-Key': 'your_api_key'},
    json={
        'query': 'sustainable fashion creators',
        'limit': 10,
    },
)

data = response.json()
for result in data['data']:
    print(result['creator']['name'], result['match']['score'])

API Reference

The API Reference is generated from the same spec as the SDK. Use it for the most up-to-date method signatures and response shapes. If the SDK types and the reference ever seem to disagree, the reference reflects the latest deployed version.