Name: Influencer & Creator Search API: Search by Niche & Email
Brand: janney
SKU: api-janney-influencer-search-api
Availability: InStock
Author: API Market

Janney AI

# Influencer & Creator Search API

## Overview

The Influencer & Creator Search API provides a powerful and streamlined way to discover social media creators and influencers across Instagram, TikTok, and YouTube from a single unified interface. This API allows you to combine natural-language queries with precise structured filters (such as niche, country, follower range, engagement rate, gender, and verified status) to find the most relevant creators. Results are semantically ranked and include valuable data points like public contact emails, engagement rates, niche tags, follower counts, and country of origin.

This API is ideal for influencer-marketing platforms, marketing agencies, brand teams, and martech / CRM tools looking to quickly identify and connect with the right creators for their campaigns and enrich their contact databases.

## Features

- **Cross-platform Search:** Access creators from Instagram, TikTok, and YouTube through a single API endpoint.
- **Natural Language & Filtered Search:** Combine free-text queries (e.g., `golf coaches in the US`) with structured filters for highly targeted results, ranked by semantic relevance.
- **Rich Filtering Options:** Filter creators by niche/topic tags, country (ISO codes), follower count range, engagement rate range (0-1), gender, verified status, and availability of a public contact email.
- **Contact-Ready Data:** Directly obtain public contact emails when available, enabling seamless transition from discovery to outreach.
- **Lookalike Search:** Find creators most similar to a given influencer's username on a specific platform, applying the same comprehensive filters.
- **Relevance-Ranked Results:** Every creator profile is returned with a relevance score, ensuring that the best matches appear first.

## Use Cases

- **Influencer Campaign Discovery:** Quickly find suitable creators for marketing campaigns based on niche, target country, audience size, and engagement metrics (e.g., `eco-friendly fashion bloggers in Germany` with `100k-500k followers`).
- **Automated Outreach List Generation:** Generate curated lists of creators complete with verified public contact emails, ready for integration into CRM systems or cold-email tools for efficient outreach.
- **Strategic Lookalike Expansion:** Leverage existing successful influencer partnerships by performing lookalike searches to discover new creators with similar profiles and audience demographics, scaling proven strategies.
- **Creator Landscape Market Research:** Map and analyze the creator ecosystem within specific niches or geographic regions to identify emerging trends, competitor activity, and untapped marketing opportunities.
- **Martech & CRM Data Enrichment:** Integrate creator profiles, engagement data, and contact information directly into marketing technology platforms and CRM systems for a comprehensive view of influencer relationships.

## Pricing

1 API unit equals 1 search query (whether `/v1/search` or `/v1/similar`). Different pricing tiers are available based on usage volume.

## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/janney/influencer-search-api`

### Authentication

Authentication is handled via an API key. Include your API key in the request header named `x-api-market-key`:
```
x-api-market-key: YOUR_API_MARKET_KEY
```
Replace `YOUR_API_MARKET_KEY` with your actual API key obtained from API.market.

### Endpoints

#### `POST /v1/search`

Search creators by natural language query and/or structured filters. Returns a ranked list of creator profiles including followers, engagement rate, niche tags, country, and public email when available.

**Request Body (`SearchReq`)**

| Parameter          | Type      | Description                                                 | Default   |
| :----------------- | :-------- | :---------------------------------------------------------- | :-------- |
| `query`            | `string`  | Natural language query (optional); merged with filters, filters take precedence. | `null`    |
| `filters`          | `object`  | An object containing various filtering criteria. See `Filters` schema below. | `{}`      |
| `sort_by`          | `string`  | Field to sort results by. Currently only `relevance` is supported. | `relevance` |
| `country_strict`   | `boolean` | If `true`, only creators explicitly located in specified countries are returned. | `false`   |
| `limit`            | `integer` | Maximum number of results to return (1-100).                | `20`      |
| `offset`           | `integer` | Offset for pagination (0 or greater).                       | `0`       |

**`Filters` Schema**

| Parameter             | Type      | Description                                                                 |
| :-------------------- | :-------- | :-------------------------------------------------------------------------- |
| `platforms`           | `string[]`| Array of platforms to search: `instagram`, `tiktok`, `youtube`.             |
| `countries`           | `string[]`| Array of ISO country codes (e.g., `US`, `GB`).                              |
| `gender`              | `string`  | Creator gender (e.g., `male`, `female`, `non_binary`).                      |
| `min_followers`       | `integer` | Minimum follower count.                                                     |
| `max_followers`       | `integer` | Maximum follower count.                                                     |
| `min_engagement_rate` | `float`   | Minimum engagement rate (0 to 1).                                           |
| `max_engagement_rate` | `float`   | Maximum engagement rate (0 to 1).                                           |
| `niche_tags`          | `string[]`| Array of topic/niche tags (e.g., `golf`, `fashion`).                        |
| `niche_match`         | `string`  | Specifies how niche tags are matched. Currently `boost` is default.         |
| `verified`            | `boolean` | If `true`, only platform-verified creators are returned.                    |
| `has_email`           | `boolean` | If `true`, only creators with a public contact email are returned.          |
| `exclude_usernames`   | `string[]`| Array of usernames/handles to exclude from results.                         |

**Response Body (`SearchResponse`)**

| Parameter     | Type        | Description                                                                 |
| :------------ | :---------- | :-------------------------------------------------------------------------- |
| `results`     | `CreatorResult[]` | Array of matching `CreatorResult` objects.                        |
| `count`       | `integer`   | Total number of results returned in this response.                          |
| `niche_matched` | `boolean`   | Indicates if niche tags were successfully matched and applied.              |
| `limit`       | `integer`   | The `limit` applied to the search.                                          |
| `offset`      | `integer`   | The `offset` applied to the search.                                         |
| `has_more`    | `boolean`   | Indicates if there are more results available beyond the current `limit` and `offset`. |
| `took_ms`     | `integer`   | Time taken to process the request in milliseconds.                          |

**`CreatorResult` Schema**

| Parameter         | Type      | Description                                     | Example               |
| :---------------- | :-------- | :---------------------------------------------- | :-------------------- |
| `platform`        | `string`  | Social media platform.                          | `instagram`           |
| `username`        | `string`  | Creator's username/handle.                      | `golfwithaimee`       |
| `display_name`    | `string`  | Creator's display name.                         | `Aimee Golf`          |
| `followers`       | `integer` | Number of followers.                            | `185000`              |
| `verified`        | `boolean` | `true` if platform-verified.                    | `true`                |
| `country`         | `string`  | ISO country code where the creator is based.    | `US`                  |
| `country_confidence`| `number`  | Confidence score for country detection (0-1). | `0.98`                |
| `gender`          | `string`  | Creator's gender.                               | `female`              |
| `niche_tags`      | `string[]`| Array of associated niche/topic tags.           | `["golf", "sports"]`  |
| `engagement_rate` | `number`  | Average engagement rate (0-1).                  | `0.043`               |
| `profile_url`     | `string`  | URL to the creator's social media profile.      | `https://instagram.com/golfwithaimee` |
| `email`           | `string`  | Public contact email, if available.             | `contact@golfwithaimee.com` |
| `bio`             | `string`  | Creator's public biography.                     | `Golf coach and enthusiast` |
| `score`           | `number`  | Relevance score for the search query (0-1).     | `0.95`                |

**Example Request**
```json
{
  "query": "golf coaches in the US",
  "filters": {
    "platforms": ["instagram"],
    "min_followers": 10000,
    "max_followers": 200000,
    "has_email": true,
    "gender": "female",
    "niche_tags": ["golf"]
  },
  "limit": 5
}
```

**cURL Example**
```bash
curl -X POST "https://prod.api.market/api/v1/janney/influencer-search-api/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "query": "golf coaches in the US",
    "filters": {
      "platforms": ["instagram"],
      "min_followers": 10000,
      "max_followers": 200000,
      "has_email": true,
      "gender": "female",
      "niche_tags": ["golf"]
    },
    "limit": 5
  }'
```

**Example Response (200 OK)**
```json
{
  "results": [
    {
      "platform": "instagram",
      "username": "golfwithaimee",
      "display_name": "Aimee Golf",
      "followers": 185000,
      "verified": true,
      "country": "US",
      "country_confidence": 0.95,
      "gender": "female",
      "niche_tags": ["golf", "sports"],
      "engagement_rate": 0.043,
      "profile_url": "https://www.instagram.com/golfwithaimee/",
      "email": "contact@golfwithaimee.com",
      "bio": "PGA Teaching Professional | Golf Content Creator | Fitness Enthusiast",
      "score": 0.98
    },
    {
      "platform": "instagram",
      "username": "usagolfcoach",
      "display_name": "USA Golf Coach",
      "followers": 75000,
      "verified": false,
      "country": "US",
      "country_confidence": 0.90,
      "gender": "male",
      "niche_tags": ["golf", "coaching"],
      "engagement_rate": 0.038,
      "profile_url": "https://www.instagram.com/usagolfcoach/",
      "email": "coach@usagolf.com",
      "bio": "Bringing you the best golf tips and drills from across the US!",
      "score": 0.91
    }
  ],
  "count": 2,
  "niche_matched": true,
  "limit": 5,
  "offset": 0,
  "has_more": true,
  "took_ms": 120
}
```

---

#### `POST /v1/similar`

Lookalike search, provide a `platform` + `username` and get the most similar creators. The same optional filters as `/v1/search` apply.

**Request Body (`SimilarReq`)**

| Parameter          | Type      | Description                                                 | Default   |
| :----------------- | :-------- | :---------------------------------------------------------- | :-------- |
| `platform`         | `string`  | The platform of the reference creator (e.g., `instagram`).  |           |
| `username`         | `string`  | The username/handle of the reference creator.               |           |
| `filters`          | `object`  | An object containing various filtering criteria for similar creators. See `Filters` schema above. | `{}`      |
| `country_strict`   | `boolean` | If `true`, only creators explicitly located in specified countries are returned. | `false`   |
| `limit`            | `integer` | Maximum number of results to return (1-100).                | `20`      |
| `offset`           | `integer` | Offset for pagination (0 or greater).                       | `0`       |

**Response Body (`SearchResponse`)**
The response schema is identical to the `SearchResponse` for the `/v1/search` endpoint.

**Example Request**
```json
{
  "platform": "instagram",
  "username": "golfwithaimee",
  "filters": {
    "platforms": ["instagram", "youtube"],
    "min_followers": 50000,
    "max_followers": 500000,
    "has_email": true
  },
  "limit": 3
}
```

**cURL Example**
```bash
curl -X POST "https://prod.api.market/api/v1/janney/influencer-search-api/v1/similar" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "platform": "instagram",
    "username": "golfwithaimee",
    "filters": {
      "platforms": ["instagram", "youtube"],
      "min_followers": 50000,
      "max_followers": 500000,
      "has_email": true
    },
    "limit": 3
  }'
```

**Example Response (200 OK)**
```json
{
  "results": [
    {
      "platform": "instagram",
      "username": "golf_swing_tips",
      "display_name": "Golf Swing Tips",
      "followers": 150000,
      "verified": false,
      "country": "US",
      "country_confidence": 0.92,
      "gender": "male",
      "niche_tags": ["golf", "training"],
      "engagement_rate": 0.039,
      "profile_url": "https://www.instagram.com/golf_swing_tips/",
      "email": "info@golfswingtips.com",
      "bio": "Master your golf swing with daily tips and tutorials.",
      "score": 0.96
    },
    {
      "platform": "youtube",
      "username": "golfacademypro",
      "display_name": "Golf Academy Pro",
      "followers": 250000,
      "verified": true,
      "country": "GB",
      "country_confidence": 0.85,
      "gender": null,
      "niche_tags": ["golf", "instruction"],
      "engagement_rate": 0.051,
      "profile_url": "https://www.youtube.com/@golfacademypro",
      "email": "contact@golfacademypro.co.uk",
      "bio": "Your ultimate guide to improving your golf game. Lessons and reviews.",
      "score": 0.90
    }
  ],
  "count": 2,
  "niche_matched": true,
  "limit": 3,
  "offset": 0,
  "has_more": false,
  "took_ms": 180
}
```

## Status Codes

- **200 OK**: Request successful. The response body contains the requested data.
- **201 Created**: (Not typically used by this API, but standard HTTP.) Resource successfully created.
- **400 Bad Request**: Invalid input parameters or malformed request. Check your request body and query parameters against the schema.
  - *Resolution*: Review the error message in the response for specific details on which parameter is incorrect or missing.
- **401 Unauthorized**: Missing or invalid API key.
  - *Resolution*: Ensure your `x-api-market-key` header is present and contains a valid API key.
- **403 Forbidden**: Valid API key but insufficient permissions. Your plan might not allow access to certain features or you've exceeded usage limits.
  - *Resolution*: Check your API.market plan details or contact support.
- **404 Not Found**: The requested resource could not be found. This typically means an incorrect endpoint path was used.
  - *Resolution*: Verify the endpoint URL `/api/v1/janney/influencer-search-api/v1/search` or `/api/v1/janney/influencer-search-api/v1/similar`.
- **422 Unprocessable Entity**: Validation Error. The request was well-formed but could not be processed due to semantic errors in the payload, often related to data types or constraints (e.g., `limit` out of range).
  - *Resolution*: Check the `detail` field in the response for specific validation issues.
- **429 Too Many Requests**: Rate limit exceeded. You have sent too many requests in a given amount of time.
  - *Resolution*: Implement a retry mechanism with exponential backoff.
- **500 Internal Server Error**: A server-side error occurred.
  - *Resolution*: This is usually a temporary issue. Retry your request. If the problem persists, contact support with the request ID if available, or the exact request body and timestamp.
- **503 Service Unavailable**: The service is temporarily unable to handle the request due to maintenance or overload.
  - *Resolution*: This is typically a transient error. Retry your request after a short delay.

## Rate Limits

API usage is subject to rate limits to ensure fair usage and service stability. If you exceed your allocated rate limit, you will receive a `429 Too Many Requests` status code. It is recommended to implement exponential backoff retry strategies when encountering rate limit errors. Higher pricing tiers typically offer increased rate limits.

## Error Handling

Effective error handling is crucial for building robust applications.
- **Interpret Error Responses**: Always check the HTTP status code first. For `4xx` and `5xx` errors, the API typically returns a JSON response containing an `error` object or `detail` field with more specific information.
- **Common Errors**:
  - `400 Bad Request` or `422 Unprocessable Entity`: These usually indicate issues with your request payload. Carefully review the error message for details on which parameter is invalid. For example, a missing required field or a value outside the allowed range.
    - `401 Unauthorized`: Verify your API key is correctly included in the `x-api-market-key` header.
    - `429 Too Many Requests`: Your application is sending requests too quickly. Implement retry logic with exponential backoff.
- **Retry Strategies**: For transient errors (e.g., `429`, `500`, `503`), implement retry logic with exponential backoff. Start with a short delay (e.g., 1 second) and increase it for subsequent retries, up to a maximum number of attempts. Avoid immediate retries as this can exacerbate the problem.

**Example Error Response (422 Unprocessable Entity)**
```json
{
  "detail": [
    {
      "loc": ["body", "limit"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}
```

## FAQ

**What social media platforms are covered by this API?**

The API covers Instagram, TikTok, and YouTube creators and influencers.

**Can I search by both natural language and specific filters?**

Yes, you can combine a natural-language query (e.g., `golf coaches`) with structured filters (e.g., `country: US`, `platform: Instagram`) in a single request. The API intelligently merges both and ranks results by relevance.

**How fresh is the creator data?**

The API regularly updates its creator database to ensure the most current follower counts, engagement rates, and profile information.

**What is the `score` in the `CreatorResult`?**

The `score` is a relevance metric, ranging from 0 to 1, indicating how well a creator matches your search query and applied filters. Higher scores mean greater relevance.

**Are contact emails always available?**

Public contact emails are included when available on the creator's profile. The `has_email: true` filter can be used to specifically find creators with an email address.

**What are ISO country codes?**

ISO country codes are internationally recognized two-letter codes for countries (e.g., `US` for United States, `GB` for Great Britain, `DE` for Germany).

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Search Instagram, TikTok & YouTube creators by niche, country, followers & engagement. Get verified emails and lookalike discovery through one simple API.

Influencer & Creator Search API: Search by Niche & Email

Free