Skip to main content

​
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.

​
TypeScript / JavaScript

​
Installation

npm install 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 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.creators.search({
  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({
  creator_ids: ['creator-uuid-1', 'creator-uuid-2'],
  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('instagram', 'jamietravels');

​
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: 'tiktok', username: 'chef_marco' },
  ],
});
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.creators.search({ query: 'fitness' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Account rate limited, retry after:', error.retryAfter);
  } 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. 503 service_unavailable on live data endpoints means a temporary upstream/platform issue; retry it with backoff and use Retry-After when present. See Error Handling for the full error reference.

​
Python

There is no official Python SDK yet. 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.