NAV Navigation
cURL Python JavaScript

NinjaPear Overview

NinjaPear is a data platform that seeks to serve as the single source of truth for B2B data, be it to power your data-driven applications or your sales-driven workflow. Our goal is to be the de-facto data platform where businesses and professionals congregate and provide first-hand data updates, in exchange for professional perks, enabling us to be a sustainable platform for ethical and legitimate data services for the rest of the data tech world.

As of today, as a data client of NinjaPear API, you can:

  1. Look up the customers, investors, and partners/platforms of any business globally.
  2. Look up the competitors of any business globally.
  3. Monitor companies for updates (blog posts, X posts, website changes) via consolidated RSS feeds.
  4. (FREE TOOL) Retrieve the logo of any company.
  5. (FREE TOOL) Find out the nature of an email address.

Authentication

curl "https://nubela.co/api/v1/customer/listing" \
  -H "Authorization: Bearer YOUR_API_KEY"

import ninjapear

configuration = ninjapear.Configuration(
    host="https://nubela.co",
    access_token="YOUR_API_KEY"
)

with ninjapear.ApiClient(configuration) as api_client:
    api = ninjapear.CustomerAPIApi(api_client)
    response = api.get_customer_listing(website="https://example.com")

var NinjaPear = require('ninjapear');
var defaultClient = NinjaPear.ApiClient.instance;
var bearerAuth = defaultClient.authentications['bearerAuth'];
bearerAuth.accessToken = "YOUR_API_KEY";

var api = new NinjaPear.CustomerAPIApi();
api.getCustomerListing("https://example.com").then(function(data) {
  console.log(data);
});

NinjaPear's API uses bearer tokens to authenticate users. Each user is assigned a randomly generated secret key under the API section in the dashboard.

The bearer token is injected in the Authorization header.

Client Libraries

We provide official client libraries for JavaScript and Python to make integrating with the NinjaPear API easier.

JavaScript (Node.js)

npm install ninjapear

# JavaScript library - see JavaScript tab

var NinjaPear = require('ninjapear');
var defaultClient = NinjaPear.ApiClient.instance;
var bearerAuth = defaultClient.authentications['bearerAuth'];
bearerAuth.accessToken = "YOUR_API_KEY";

// Now you can use any API class
var companyApi = new NinjaPear.CompanyAPIApi();
var customerApi = new NinjaPear.CustomerAPIApi();
var contactApi = new NinjaPear.ContactAPIApi();
var metaApi = new NinjaPear.MetaAPIApi();

Python

uv add ninjapear
# or: pip install ninjapear

import ninjapear

configuration = ninjapear.Configuration(
    host="https://nubela.co",
    access_token="YOUR_API_KEY"
)

# Use the client with a context manager
with ninjapear.ApiClient(configuration) as api_client:
    company_api = ninjapear.CompanyAPIApi(api_client)
    customer_api = ninjapear.CustomerAPIApi(api_client)
    contact_api = ninjapear.ContactAPIApi(api_client)
    meta_api = ninjapear.MetaAPIApi(api_client)

// Python library - see Python tab

Rate limit

You can make up to 300 requests to our API every minute. The window for the rate limit is 5 minutes. This means you can burst up to 1500 requests every 5 minutes.

At periods of high load, our system might tighten rate limits for all accounts to ensure that our services remain accessible for all users.

We return a status code of error 429 when you are rate limited. You can also get a status code error of 429 if the capacity on our end limits us.

You should handle 429 errors and apply exponential backoff.

Accounts on trial (that is before any top ups have been made) are limited to 2 requests every minute. You get the normal rate limit upon making at least one credit top-up.

Rate limit for Free APIs

To sustainably provide free APIs, rate limit for free APIs depends on your subscription plan:

Credits

Each valid request requires at least 0.1 credit to be processed, unless it is a free API endpoint.

A credit is consumed if and only if the request is parsed successfully.

A successful request is a request that returns with a 200 HTTP status code.

Timeouts and API response time

NinjaPear API endpoints take 30-60 seconds to complete.

You are encouraged to make concurrent requests to our API service to maximize throughput. See this post on how you can maximise throughput.

We recommend a timeout of 100 seconds.

Errors

These are the common errors that could be returned by our API:

HTTP Code Charge? Description
400 No Invalid parameters provided. Refer to the documentation and message body for more info
401 No Invalid API Key
403 No You have run out of credits
404 Yes The requested resource (e.g., user profile, company) could not be found
410 No This API is deprecated
429 No Rate limited. Please retry
500 No There is an error with our API. Please Contact us for assistance
503 No Enrichment failed, please retry.

You will never be charged for failed requests.

Backward Compatibility Guarantee

We are committed to ensuring that our API remains backward compatible, allowing you to integrate with confidence. Our backward compatibility guarantee means that we will not introduce changes that break existing functionality or remove endpoints without a deprecation period.

To be specific, we will not introduce breaking changes in the following ways:

  1. We will not remove documented parameters and response attributes.
  2. We will not change the data type as documented in our API responses.

However, the following are not considered breaking changes:

We highly recommend integrating our API in a way that would not break should new response attributes or headers be introduced.

If we make changes to our API, we will provide clear documentation and sufficient notice (30 days) to ensure a seamless transition. Notices will be shared via newsletter emails, Twitter/X posts and updates to our blog.

Customer API

Customer Listing Endpoint

GET /api/v1/customer/listing

Cost: 1 credit / request + 2 credit / company returned. Credits are charged even when the request returns an empty result.

Get a list of highly-probable customers, investors, and partners/platforms of a target company, categorized by relationship type.

curl -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "website=https://www.stripe.com" \
  "https://nubela.co/api/v1/customer/listing"

import ninjapear

configuration = ninjapear.Configuration(
    host="https://nubela.co",
    access_token="YOUR_API_KEY"
)

with ninjapear.ApiClient(configuration) as api_client:
    api = ninjapear.CustomerAPIApi(api_client)
    response = api.get_customer_listing(website="https://www.stripe.com")
    print(response)

var NinjaPear = require('ninjapear');
var defaultClient = NinjaPear.ApiClient.instance;
defaultClient.authentications['bearerAuth'].accessToken = "YOUR_API_KEY";

var api = new NinjaPear.CustomerAPIApi();
api.getCustomerListing("https://www.stripe.com").then(function(data) {
  console.log(data);
});

Example response:

{
  "customers": [
    {
      "name": "Apple",
      "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.",
      "tagline": "Think different.",
      "website": "https://www.apple.com",
      "company_logo_url": "https://nubela.co/api/v1/company/logo?website=https%3A%2F%2Fwww.apple.com",
      "id": "abc123",
      "industry": 45202030,
      "specialties": ["Technology", "Consumer Electronics"],
      "x_profile": "https://x.com/Apple"
    }
  ],
  "investors": [
    {
      "name": "Sequoia Capital",
      "description": "Sequoia Capital is a venture capital firm focused on technology companies.",
      "tagline": null,
      "website": "https://www.sequoiacap.com",
      "company_logo_url": "https://nubela.co/api/v1/company/logo?website=https%3A%2F%2Fwww.sequoiacap.com",
      "id": "def456",
      "industry": 40203010,
      "specialties": ["Venture Capital", "Growth Equity"],
      "x_profile": "https://x.com/sequoia"
    }
  ],
  "partner_platforms": [
    {
      "name": "Amazon Web Services",
      "description": "Amazon Web Services provides cloud computing platforms and APIs.",
      "tagline": null,
      "website": "https://aws.amazon.com",
      "company_logo_url": "https://nubela.co/api/v1/company/logo?website=https%3A%2F%2Faws.amazon.com",
      "id": "ghi789",
      "industry": 45101010,
      "specialties": ["Cloud Computing", "Infrastructure"],
      "x_profile": "https://x.com/awscloud"
    }
  ],
  "next_page": "https://nubela.co/api/v1/customer/listing?website=https://www.stripe.com&cursor=abc123"
}

URL Parameters

Parameter Required Description Example
website Yes The website URL of the target company https://www.stripe.com
cursor No Pagination cursor from next_page in a previous response abc123
page_size No Number of results per page (1-200, default 200) 50
quality_filter No Filter out low-quality results (junk TLDs like .top, .xyz and unreachable websites). Set to false to include all results. (default: true) false

Response

Key Description Example
customers A list of companies that are probable customers of the target company. Entities that pay for the target's product/service. List of CustomerCompany objects
investors A list of companies that are investors (VC firms, PE funds, angel networks) of the target company. List of CustomerCompany objects
partner_platforms A list of companies that are partners, platforms, or service providers the target company uses or integrates with (tech stack, media, agencies). List of CustomerCompany objects
next_page The API URI that serves as the cursor for pagination. Following this URL with your API key will lead to the next page of results. This will be null for the final page. https://nubela.co/api/v1/customer/list?...

Error Codes

Status Code Charged? Description
400 No Unable to extract enough information about the target company

CustomerCompany

Key Description Example
name Company name "Apple"
description A brief description of the company "Apple Inc. designs, manufactures, and markets smartphones..."
tagline Company tagline or slogan "Think different."
website Company website URL "https://www.apple.com"
company_logo_url URL to the Company Logo API for this company. Powered by Company Logo Endpoint. Authenticate with your bearer token. null if no website. "https://nubela.co/api/v1/company/logo?website=https%3A%2F%2Fwww.apple.com"
id Unique identifier "abc123"
industry GICS 8-digit industry code 45202030
specialties List of company specialties ["Technology"]
x_profile X (Twitter) profile URL "https://x.com/Apple"

Note on company_logo_url: This URL is powered by the Company Logo Endpoint. Authenticate with your Bearer token (same as the main API). These are temporal links — the recommended approach is to download the image via the URL as soon as the response is returned and host the image on your end.

Response Headers

Header Key Description Example
X-NinjaPear-Credit-Cost Total cost of credits for this API call 10

Competitor API

Competitor Listing Endpoint

GET /api/v1/competitor/listing

Cost: 2 credits / competitor returned. Minimum 5 credits per request, charged even when no results are found.

Get a list of competitor companies for a target company, with the reason for competition.

curl -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "website=https://www.stripe.com" \
  "https://nubela.co/api/v1/competitor/listing"

import ninjapear

configuration = ninjapear.Configuration(
    host="https://nubela.co",
    access_token="YOUR_API_KEY"
)

with ninjapear.ApiClient(configuration) as api_client:
    api = ninjapear.CompetitorAPIApi(api_client)
    response = api.get_competitor_listing(website="https://www.stripe.com")
    print(response)

var NinjaPear = require('ninjapear');
var defaultClient = NinjaPear.ApiClient.instance;
defaultClient.authentications['bearerAuth'].accessToken = "YOUR_API_KEY";

var api = new NinjaPear.CompetitorAPIApi();
api.getCompetitorListing("https://www.stripe.com").then(function(data) {
  console.log(data);
});

Example response:

{
  "competitors": [
    {
      "company_details_url": "https://nubela.co/api/v1/company/details?website=https://www.adyen.com",
      "website": "https://www.adyen.com",
      "competition_reason": "product_overlap"
    },
    {
      "company_details_url": "https://nubela.co/api/v1/company/details?website=https://squareup.com",
      "website": "https://squareup.com",
      "competition_reason": "product_overlap"
    },
    {
      "company_details_url": "https://nubela.co/api/v1/company/details?website=https://www.checkout.com",
      "website": "https://www.checkout.com",
      "competition_reason": "organic_keyword_overlap"
    }
  ]
}

URL Parameters

Parameter Required Description Example
website Yes The website URL of the target company https://www.stripe.com

Response

Key Description Example
competitors A list of competitor companies for the target company. List of CompetitorCompany objects

Error Codes

Status Code Charged? Description
400 No Unable to extract enough information about the target company

CompetitorCompany

Key Description Example
company_details_url URL to the Company Details endpoint for this competitor. Authenticate with your bearer token to retrieve full company details. "https://nubela.co/api/v1/company/details?website=https://www.adyen.com"
website Company website URL "https://www.adyen.com"
competition_reason Why this company is considered a competitor. One of the values from the Competition Reason enum. "product_overlap"

Competition Reason Enum

Value Description
organic_keyword_overlap Both companies rank for similar organic search keywords
product_overlap Both companies offer similar products or services

Response Headers

Header Key Description Example
X-NinjaPear-Credit-Cost Total cost of credits for this API call 4

Company API

Company Logo Endpoint

GET /api/v1/company/logo

Cost: 0 credit / successful request. (FREE)

Retrieve the logo of a company given its website URL. Returns the logo as a PNG image (128x128).

curl -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "website=https://www.stripe.com" \
  "https://nubela.co/api/v1/company/logo" \
  --output logo.png

import ninjapear

configuration = ninjapear.Configuration(
    host="https://nubela.co",
    access_token="YOUR_API_KEY"
)

with ninjapear.ApiClient(configuration) as api_client:
    api = ninjapear.CompanyAPIApi(api_client)
    logo_data = api.get_company_logo(website="https://www.stripe.com")

    # Save the logo image
    with open("logo.png", "wb") as f:
        f.write(logo_data)

var NinjaPear = require('ninjapear');
var fs = require('fs');
var defaultClient = NinjaPear.ApiClient.instance;
defaultClient.authentications['bearerAuth'].accessToken = "YOUR_API_KEY";

var api = new NinjaPear.CompanyAPIApi();
api.getCompanyLogo("https://www.stripe.com").then(function(data) {
  // Save the logo image
  fs.writeFileSync("logo.png", Buffer.from(data));
});

Example response:

Company Logo Example

A raw PNG image binary (Content-Type: image/png).

URL Parameters

Parameter Required Description Example
website Yes The website URL of the target company https://www.stripe.com

Response

A 200 response returns the logo as a raw PNG image with Content-Type: image/png.

Error Codes

Status Code Charged? Description
404 No No logo found for the given domain

Response Headers

Header Key Description Example
X-NinjaPear-Credit-Cost Total cost of credits for this API call 0

Company Details Endpoint

GET /api/v1/company/details

Cost: 2 credits / request (base). Add 2 credits when include_employee_count=true (total: 4 credits). Credits are charged even if no data found.

Retrieve the details of a company given its website URL. Returns company metadata including description, industry, social media URLs, and more.

curl -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "website=https://www.stripe.com" \
  "https://nubela.co/api/v1/company/details"

import ninjapear

configuration = ninjapear.Configuration(
    host="https://nubela.co",
    access_token="YOUR_API_KEY"
)

with ninjapear.ApiClient(configuration) as api_client:
    api = ninjapear.CompanyAPIApi(api_client)
    details = api.get_company_details(website="https://www.stripe.com")
    print(details)

var NinjaPear = require('ninjapear');
var defaultClient = NinjaPear.ApiClient.instance;
defaultClient.authentications['bearerAuth'].accessToken = "YOUR_API_KEY";

var api = new NinjaPear.CompanyAPIApi();
api.getCompanyDetails("https://www.stripe.com").then(function(data) {
  console.log(data);
});

Example response (private company):

{
  "websites": [
    "https://stripe.com",
    "https://stripe.dev"
  ],
  "description": "Stripe is a technology company that builds economic infrastructure for the internet.",
  "industry": 45102010,
  "company_type": "PRIVATELY_HELD",
  "founded_year": 2010,
  "specialties": ["Payments", "Financial Services", "APIs"],
  "name": "Stripe",
  "tagline": "Financial infrastructure for the internet",
  "logo_url": "https://nubela.co/api/v1/company/logo?website=https://stripe.com",
  "cover_pic_url": "https://example.com/stripe-cover.png",
  "facebook_url": "https://facebook.com/stripe",
  "twitter_url": "https://twitter.com/stripe",
  "instagram_url": null,
  "employee_count": 8000,
  "addresses": [
    {
      "address_type": "HEADQUARTERS",
      "line1": "354 Oyster Point Blvd",
      "line2": null,
      "city": "South San Francisco",
      "state": "CA",
      "postal_code": "94080",
      "country_code": "US",
      "country": "United States",
      "is_primary": true
    }
  ],
  "executives": [
    {
      "name": "Patrick Collison",
      "title": "Chief Executive Officer",
      "role": "CEO"
    }
  ],
  "public_listing": null
}

Example response (public company):

{
  "websites": ["https://apple.com"],
  "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.",
  "industry": 45202030,
  "company_type": "PUBLIC_COMPANY",
  "founded_year": 1976,
  "specialties": ["Consumer Electronics", "Software", "Services"],
  "name": "Apple",
  "tagline": "Think different",
  "logo_url": "https://nubela.co/api/v1/company/logo?website=https://apple.com",
  "cover_pic_url": "https://example.com/apple-cover.png",
  "facebook_url": "https://facebook.com/apple",
  "twitter_url": "https://twitter.com/apple",
  "instagram_url": "https://instagram.com/apple",
  "employee_count": 164000,
  "addresses": [
    {
      "address_type": "HEADQUARTERS",
      "line1": "One Apple Park Way",
      "line2": null,
      "city": "Cupertino",
      "state": "CA",
      "postal_code": "95014",
      "country_code": "US",
      "country": "United States",
      "is_primary": true
    }
  ],
  "executives": [
    {
      "name": "Tim Cook",
      "title": "Chief Executive Officer",
      "role": "CEO"
    }
  ],
  "public_listing": {
    "stock_symbol": "AAPL",
    "ipo_date": "1980-12-12",
    "isin": "US0378331005",
    "figi": "BBG000B9XRY4",
    "cusip": "037833100",
    "lei": "HWUPKR0MPOU8FGXBT394",
    "cik": "0000320193",
    "sic_code": "3571",
    "revenue_usd": 383285000000,
    "revenue_captured_at": "2024-09-28",
    "ebitda_usd": 134000000000,
    "ebitda_captured_at": "2024-09-28"
  }
}

URL Parameters

Parameter Required Description Example
website Yes The website URL of the target company https://www.stripe.com
include_employee_count No Fetch fresh employee count data via web search. Adds 2 credits to the request cost. true

Response

Key Description Example
websites List of all company website URLs ["https://stripe.com", "https://stripe.dev"]
description A brief description of the company "Stripe is a technology company..."
industry GICS 8-digit industry code 45102010
company_type Type of company (PUBLIC_COMPANY, PRIVATELY_HELD, GOVERNMENT_AGENCY, NON_PROFIT, EDUCATIONAL, PARTNERSHIP, SELF_EMPLOYED, SELF_OWNED) "PRIVATELY_HELD"
founded_year Year the company was founded 2010
specialties List of company specialties ["Payments", "Financial Services"]
name Company name "Stripe"
tagline Company tagline or slogan "Financial infrastructure for the internet"
logo_url URL to the company logo endpoint. Authenticate with your API key bearer token. "https://nubela.co/api/v1/company/logo?website=https://stripe.com"
cover_pic_url URL to the company's cover/banner image "https://example.com/cover.png"
facebook_url Facebook profile URL "https://facebook.com/stripe"
twitter_url Twitter/X profile URL "https://twitter.com/stripe"
instagram_url Instagram profile URL null
employee_count Estimated number of employees 8000
employee_count_range_min Lower bound of employee count range. Only present when include_employee_count=true. 7500
employee_count_range_max Upper bound of employee count range. Only present when include_employee_count=true. 8500
addresses List of company addresses [Address Object]
executives List of company executives and board members [Executive Object]
public_listing Public company data including stock info and financials. null for private companies. PublicListing Object

Address Object

Key Description Example
address_type Type of address (HEADQUARTERS, REGISTERED, BRANCH, MAILING, OTHER) "HEADQUARTERS"
line1 Street address line 1 "354 Oyster Point Blvd"
line2 Street address line 2 null
city City name "South San Francisco"
state State, province, or region "CA"
postal_code Postal/ZIP code "94080"
country_code ISO 3166-1 alpha-2 country code "US"
country Full country name "United States"
is_primary Whether this is the primary address true

Executive Object

Key Description Example
name Full name of the executive "Patrick Collison"
title Job title "Chief Executive Officer"
role Normalized role type (CEO, CFO, COO, CTO, CMO, PRESIDENT, VICE_PRESIDENT, DIRECTOR, BOARD_MEMBER, CHAIRMAN, FOUNDER, OTHER) "CEO"

PublicListing Object

This object is only present (non-null) for public companies. For private companies, public_listing will be null.

Key Description Example
stock_symbol Stock ticker symbol "AAPL"
ipo_date IPO date in ISO format "1980-12-12"
isin International Securities Identification Number "US0378331005"
figi Financial Instrument Global Identifier "BBG000B9XRY4"
cusip CUSIP identifier "037833100"
lei Legal Entity Identifier "HWUPKR0MPOU8FGXBT394"
cik SEC Central Index Key "0000320193"
sic_code SEC Standard Industrial Classification code "3571"
revenue_usd Annual revenue in USD 383285000000
revenue_captured_at Date when revenue data was captured (ISO format) "2024-09-28"
ebitda_usd EBITDA in USD 134000000000
ebitda_captured_at Date when EBITDA data was captured (ISO format) "2024-09-28"

Response Headers

Header Key Description Example
X-NinjaPear-Credit-Cost Total cost of credits for this API call 2

Error Codes

Status Code Charged? Description
400 No Website is unreachable
404 Yes No company data could be extracted from the website

Employee Count Endpoint

GET /api/v1/company/employee-count

Cost: 2 credits / successful request.

Retrieve the employee count range for a company given its website URL.

curl -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "website=https://www.stripe.com" \
  "https://nubela.co/api/v1/company/employee-count"

import ninjapear

configuration = ninjapear.Configuration(
    host="https://nubela.co",
    access_token="YOUR_API_KEY"
)

with ninjapear.ApiClient(configuration) as api_client:
    api = ninjapear.CompanyAPIApi(api_client)
    response = api.get_employee_count(website="https://www.stripe.com")
    print(response)

var NinjaPear = require('ninjapear');
var defaultClient = NinjaPear.ApiClient.instance;
defaultClient.authentications['bearerAuth'].accessToken = "YOUR_API_KEY";

var api = new NinjaPear.CompanyAPIApi();
api.getEmployeeCount("https://www.stripe.com").then(function(data) {
  console.log(data);
});

Example response:

{
  "employee_count": 3500
}

URL Parameters

Parameter Required Description Example
website Yes The website URL of the target company https://www.stripe.com

Response

Key Description Example
employee_count Estimated employee count 3500

Response Headers

Header Key Description Example
X-NinjaPear-Credit-Cost Total cost of credits for this API call 2

Error Codes

Status Code Charged? Description
404 No No employee count data found for the given website

Meta API

View Credit Balance Endpoint

GET /api/v1/meta/credit-balance

Cost: 0 credit / successful request.

Get your current credit balance.

curl -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://nubela.co/api/v1/meta/credit-balance"

import ninjapear

configuration = ninjapear.Configuration(
    host="https://nubela.co",
    access_token="YOUR_API_KEY"
)

with ninjapear.ApiClient(configuration) as api_client:
    api = ninjapear.MetaAPIApi(api_client)
    response = api.get_credit_balance()
    print(response)

var NinjaPear = require('ninjapear');
var defaultClient = NinjaPear.ApiClient.instance;
defaultClient.authentications['bearerAuth'].accessToken = "YOUR_API_KEY";

var api = new NinjaPear.MetaAPIApi();
api.getCreditBalance().then(function(data) {
  console.log(data);
});

Example response:

{
  "credit_balance": 100000
}

Response

Key Description Example
credit_balance Your current credit balance 100000

Response Headers

Header Key Description Example
X-NinjaPear-Credit-Cost Total cost of credits for this API call 0

Error Codes

Status Code Charged? Description
401 No Invalid API key

Contact API

Disposable Email Checker Endpoint

GET /api/v1/contact/disposable-email

Cost: 0 credit / successful request. (FREE)

Check if an email address is a disposable (temporary/throwaway) email or a free email provider.

curl -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "[email protected]" \
  "https://nubela.co/api/v1/contact/disposable-email"

import ninjapear

configuration = ninjapear.Configuration(
    host="https://nubela.co",
    access_token="YOUR_API_KEY"
)

with ninjapear.ApiClient(configuration) as api_client:
    api = ninjapear.ContactAPIApi(api_client)
    response = api.check_disposable_email(email="[email protected]")
    print(response)

var NinjaPear = require('ninjapear');
var defaultClient = NinjaPear.ApiClient.instance;
defaultClient.authentications['bearerAuth'].accessToken = "YOUR_API_KEY";

var api = new NinjaPear.ContactAPIApi();
api.checkDisposableEmail("[email protected]").then(function(data) {
  console.log(data);
});

Example response:

{
  "email": "[email protected]",
  "is_disposable_email": true,
  "is_free_email": false
}

URL Parameters

Parameter Required Description Example
email Yes The email address to check [email protected]

Response

Key Description Example
email The email address that was checked "[email protected]"
is_disposable_email Whether the email domain is a known disposable/temporary email provider true
is_free_email Whether the email domain is a free email provider (e.g., gmail.com, yahoo.com) false

Response Headers

Header Key Description Example
X-NinjaPear-Credit-Cost Total cost of credits for this API call 0

Error Codes

Status Code Charged? Description
400 No Invalid email format

Updates API

The Updates API allows you to monitor updates of companies. Every new update is compiled into a single RSS feed. The system monitors company blogs, X (Twitter) profiles, and website changes.

Core Concepts

How To Use

Suppose you want to monitor a group of competitor websites for blog posts, X activity, and website changes — all delivered as a single RSS feed you can plug into Feedly, Slack, Zapier, or any RSS reader.

1. Create a feed with targets — group the companies you want to monitor into a feed. Each company is a target identified by its website URL.

curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "SaaS Competitors", "targets": [ { "website_url": "https://stripe.com" }, { "website_url": "https://shopify.com" }, { "website_url": "https://vercel.com" } ] }' \ "https://nubela.co/api/v1/feeds"

The response includes an rss_url — this is the URL you subscribe to.

{ "id": "feed_abc123", "rss_url": "https://nubela.co/.../rss.xml?token=sec_live_..." }

2. Subscribe to the RSS feed — copy the rss_url and add it to any RSS reader (Feedly, Slack, Zapier, etc.). Blog posts, X posts, and website changes from all targets appear as items in a single feed.

Stripe: Expanding our Payment Network [blog] Vercel on X: "Next.js 16 is here" [x] Shopify: Pricing Page [website update]

Each item includes a category (blog, x, website update, or website new page). See Consume Feed Endpoint for the full RSS schema.

3. Add new targets — a new competitor entered the market? Add them to the feed.

curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "website_url": "https://linear.app" }' \ "https://nubela.co/api/v1/feeds/feed_abc123/targets"

4. Remove targets — a company is no longer relevant? Remove it from the feed.

curl -X DELETE \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://nubela.co/api/v1/feeds/feed_abc123/targets/target_xyz789"

5. Change monitoring settings — by default every target monitors blog posts, X posts, and website changes on a 7-day cadence. Use PATCH to toggle channels or change the frequency.

curl -X PATCH \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "settings": { "monitor_x": false, "frequency_days": 1 } }' \ "https://nubela.co/api/v1/feeds/feed_abc123/targets/target_xyz789"

Only the fields you include are changed — omitted fields keep their current values. See Settings Object for all available options.

Pricing

Action Cost
Create a feed 3 credits (one-time)
Blog post pull (per target) 1 credit/pull
Website monitoring pull (per target) 1 credit/pull
X post updates pull (per target) 2 credits/pull
All other endpoints (list, describe, delete feeds; manage targets) 0 credits

Each pull checks one target for one source (blog, X, or website). With all three sources enabled, a single target costs 4 credits per pull (1 blog + 2 X + 1 website).

Example monthly costs

Scenario Targets Frequency Credits/month
VC tracking 20 portfolio companies 20 Weekly ~346 credits (3 one-time + 20 × 4 × 4.3 weeks)
Startup monitoring 10 competitors 10 Daily ~1,203 credits (3 one-time + 10 × 4 × 30 days)
Sales team watching 5 prospect accounts (blog + X only, no website) 5 Daily ~453 credits (3 one-time + 5 × 3 × 30 days)

One-time feed creation cost (3 credits) is included in the first month only.

List Feeds Endpoint

GET /api/v1/feeds

Cost: 0 credits / request.

Retrieves a list of all feeds owned by the authenticated user.

curl -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://nubela.co/api/v1/feeds"

Example response:

{
  "feeds": [
    {
      "id": "feed_abc123",
      "name": "SaaS Competitors",
      "is_public": false,
      "rss_url": "https://nubela.co/api/v1/feeds/feed_abc123/rss.xml?token=sec_live_987654321",
      "created_at": "2026-02-24T00:00:00Z",
      "target_count": 2
    }
  ]
}

Response

Key Description Example
feeds List of Feed objects See Feed Object

Feed Object

Key Description Example
id Unique feed identifier "feed_abc123"
name Feed name "SaaS Competitors"
is_public Whether the feed is publicly accessible false
is_suspended Whether the feed is currently suspended false
suspension_reason Reason for suspension, if suspended null or "insufficient_credits"
rss_url The RSS feed URL. For private feeds, includes a token query parameter. "https://nubela.co/api/v1/feeds/feed_abc123/rss.xml?token=sec_live_987654321"
email_notifications Email notification mode "skip" or "on_updates"
created_at ISO 8601 creation timestamp "2026-02-24T00:00:00Z"
target_count Number of targets in the feed 2

New Feed Endpoint

POST /api/v1/feeds

Cost: 3 credits / request (one-time fee).

Creates a new feed and optionally accepts an array of initial targets.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SaaS Competitors",
    "is_public": false,
    "targets": [
      {
        "website_url": "https://stripe.com",
        "settings": {
          "monitor_blog": true,
          "monitor_x": true,
          "monitor_website": true,
          "frequency_days": 7
        }
      },
      {
        "website_url": "https://vercel.com"
      }
    ]
  }' \
  "https://nubela.co/api/v1/feeds"

Example response 201 Created:

{
  "id": "feed_abc123",
  "name": "SaaS Competitors",
  "is_public": false,
  "is_suspended": false,
  "suspension_reason": null,
  "rss_url": "https://nubela.co/api/v1/feeds/feed_abc123/rss.xml?token=sec_live_987654321",
  "created_at": "2026-02-24T09:55:00Z",
  "targets": [
    {
      "id": "target_xyz789",
      "website_url": "https://stripe.com",
      "settings": {
        "monitor_blog": true,
        "monitor_x": true,
        "monitor_website": true,
        "frequency_days": 7
      },
      "last_polled_at": null,
      "is_baseline_complete": false,
      "created_at": "2026-02-24T09:55:00Z"
    },
    {
      "id": "target_xyz790",
      "website_url": "https://vercel.com",
      "settings": {
        "monitor_blog": true,
        "monitor_x": true,
        "monitor_website": true,
        "frequency_days": 7
      },
      "last_polled_at": null,
      "is_baseline_complete": false,
      "created_at": "2026-02-24T09:55:00Z"
    }
  ]
}

Request Body

Parameter Required Description Example
name No Name of the feed. If omitted, a name will be auto-generated. "SaaS Competitors"
is_public No Whether the feed is publicly accessible (default: false) false
email_notifications No Email notification mode. "on_updates" to receive emails when new updates are detected, "skip" to disable (default: "skip") "on_updates"
targets Yes Array of initial targets to add to the feed (at least 1 required) See Target Input Object

Target Input Object

Parameter Required Description Example
website_url Yes The website URL of the company to monitor "https://stripe.com"
settings No Monitoring preferences. If omitted, defaults apply. See Settings Object

Settings Object

Parameter Required Description Example
monitor_blog No Monitor the company's blog for new posts (default: true) true
monitor_x No Monitor the company's X (Twitter) account (default: true) true
monitor_website No Monitor the company's website for content changes and new pages (default: true) true
frequency_days No How often to check for updates, in days. Must be between 1 and 30 (default: 7) 7

Validation Rules

Response

Returns 201 Created. The response includes the created Feed Object with an additional targets array containing Target Object entries.

Target Object

Key Description Example
id Unique target identifier "target_xyz789"
website_url The monitored company's website URL "https://stripe.com"
settings Monitoring preferences object See Settings Object
last_polled_at ISO 8601 timestamp of the last poll, or null if never polled null
is_baseline_complete Whether the initial baseline snapshot has been captured false
created_at ISO 8601 creation timestamp "2026-02-24T09:55:00Z"

Response Headers

Header Key Description Example
X-NinjaPear-Credit-Cost Total cost of credits for this API call 3

Error Codes

Status Code Charged? Description
400 No Validation error (missing targets, unreachable URL, no monitor flags enabled)

Describe Feed Endpoint

GET /api/v1/feeds/{feed_id}

Cost: 0 credits / request.

Retrieves full details of a single feed, including all its attached targets.

curl -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://nubela.co/api/v1/feeds/feed_abc123"

Example response:

{
  "id": "feed_abc123",
  "name": "SaaS Competitors",
  "is_public": false,
  "is_suspended": false,
  "suspension_reason": null,
  "rss_url": "https://nubela.co/api/v1/feeds/feed_abc123/rss.xml?token=sec_live_987654321",
  "created_at": "2026-02-24T09:55:00Z",
  "targets": [
    {
      "id": "target_xyz789",
      "website_url": "https://stripe.com",
      "settings": {
        "monitor_blog": true,
        "monitor_x": true,
        "monitor_website": true,
        "frequency_days": 7
      },
      "last_polled_at": "2026-02-24T12:00:00Z",
      "is_baseline_complete": true,
      "created_at": "2026-02-24T09:55:00Z"
    },
    {
      "id": "target_xyz790",
      "website_url": "https://vercel.com",
      "settings": {
        "monitor_blog": true,
        "monitor_x": true,
        "monitor_website": true,
        "frequency_days": 7
      },
      "last_polled_at": null,
      "is_baseline_complete": false,
      "created_at": "2026-02-24T09:55:00Z"
    }
  ]
}

URL Parameters

Parameter Required Description Example
feed_id Yes The ID of the feed feed_abc123

Response

Returns a Feed Object with an additional targets array containing Target Object entries.

Error Codes

Status Code Charged? Description
404 No Feed not found

Delete Feed Endpoint

DELETE /api/v1/feeds/{feed_id}

Cost: 0 credits / request.

Permanently deletes a feed and all associated targets.

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://nubela.co/api/v1/feeds/feed_abc123"

URL Parameters

Parameter Required Description Example
feed_id Yes The ID of the feed to delete feed_abc123

Response

Returns 200 OK with a confirmation message.

{
  "message": "Feed deleted."
}

Error Codes

Status Code Charged? Description
404 No Feed not found

Add Target Endpoint

POST /api/v1/feeds/{feed_id}/targets

Cost: 0 credits / request.

Adds a new company to an existing feed.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "website_url": "https://shopify.com",
    "settings": {
      "monitor_blog": true,
      "monitor_x": true,
      "monitor_website": false,
      "frequency_days": 3
    }
  }' \
  "https://nubela.co/api/v1/feeds/feed_abc123/targets"

Example response 201 Created:

{
  "id": "target_xyz791",
  "website_url": "https://shopify.com",
  "settings": {
    "monitor_blog": true,
    "monitor_x": true,
    "monitor_website": false,
    "frequency_days": 3
  },
  "last_polled_at": null,
  "is_baseline_complete": false,
  "created_at": "2026-02-24T10:00:00Z"
}

URL Parameters

Parameter Required Description Example
feed_id Yes The ID of the feed to add the target to feed_abc123

Request Body

Parameter Required Description Example
website_url Yes The website URL of the company to monitor "https://shopify.com"
settings No Monitoring preferences. If omitted, defaults apply. See Settings Object

Response

Returns a Target Object.

Error Codes

Status Code Charged? Description
404 No Feed not found

Update Target Endpoint

PATCH /api/v1/feeds/{feed_id}/targets/{target_id}

Cost: 0 credits / request.

Modifies the monitoring preferences for a specific target.

curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "frequency_days": 1,
      "monitor_website": true
    }
  }' \
  "https://nubela.co/api/v1/feeds/feed_abc123/targets/target_xyz789"

URL Parameters

Parameter Required Description Example
feed_id Yes The ID of the feed feed_abc123
target_id Yes The ID of the target to update target_xyz789

Request Body

Parameter Required Description Example
settings Yes Partial settings update. Only provided fields are changed. See Settings Object

Response

Returns the updated Target Object.

Example response:

{
  "id": "target_xyz789",
  "website_url": "https://stripe.com",
  "settings": {
    "monitor_blog": true,
    "monitor_x": true,
    "monitor_website": true,
    "frequency_days": 1
  },
  "last_polled_at": "2026-02-24T12:00:00Z",
  "is_baseline_complete": true,
  "created_at": "2026-02-24T09:55:00Z"
}

Error Codes

Status Code Charged? Description
400 No No valid settings provided
404 No Feed or target not found

Remove Target Endpoint

DELETE /api/v1/feeds/{feed_id}/targets/{target_id}

Cost: 0 credits / request.

Stops monitoring a website and removes it from the feed.

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://nubela.co/api/v1/feeds/feed_abc123/targets/target_xyz789"

URL Parameters

Parameter Required Description Example
feed_id Yes The ID of the feed feed_abc123
target_id Yes The ID of the target to remove target_xyz789

Response

Returns 200 OK with a confirmation message.

{
  "message": "Target deleted."
}

Error Codes

Status Code Charged? Description
404 No Feed or target not found

Consume Feed Endpoint

GET /api/v1/feeds/{feed_id}/rss.xml

Cost: 0 credits / request (monitoring costs are incurred per-pull on each target — see Pricing).

Returns a standard RSS 2.0 XML feed consumed by RSS readers (Feedly, Slack, browser extensions, etc.).

If the feed's is_public is false, a valid token must be passed as a token query parameter.

curl "https://nubela.co/api/v1/feeds/feed_abc123/rss.xml?token=YOUR_RSS_TOKEN"

Example response:

<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/">
<channel>
  <title>SaaS Competitors</title>
  <link>https://nubela.co/api/v1/feeds/feed_abc123/rss.xml</link>
  <description>Automated updates for Stripe, Shopify, and Vercel.</description>
  <lastBuildDate>Tue, 24 Feb 2026 10:00:00 +0800</lastBuildDate>

  <item>
    <title>Stripe: Expanding our Global Payment Network</title>
    <link>https://stripe.com/blog/global-network-2026</link>
    <guid isPermaLink="true">https://stripe.com/blog/global-network-2026</guid>
    <pubDate>Mon, 23 Feb 2026 14:30:00 +0800</pubDate>
    <category>blog</category>
    <dc:creator>Stripe</dc:creator>
    <description>Stripe is expanding its payments infrastructure to 15 new countries, enabling merchants to accept local payment methods seamlessly.</description>
    <enclosure url="https://b.stripecdn.com/blog/og-global-network.jpg" length="150000" type="image/jpeg" />
  </item>

  <item>
    <title>Vercel on X: "Next.js 16 is here..."</title>
    <link>https://x.com/vercel/status/123456789</link>
    <guid isPermaLink="false">x_post_123456789</guid>
    <pubDate>Sun, 22 Feb 2026 10:15:00 +0800</pubDate>
    <category>x</category>
    <dc:creator>Vercel</dc:creator>
    <description>Next.js 16 is here, featuring completely redesigned server components and faster builds. Read the changelog.</description>
    <enclosure url="https://pbs.twimg.com/media/vercel-next16.jpg" length="85000" type="image/jpeg" />
  </item>

  <item>
    <title>Shopify: Pricing Page</title>
    <link>https://shopify.com/pricing</link>
    <guid isPermaLink="false">website_update_shopify_pricing_1708416000</guid>
    <pubDate>Fri, 20 Feb 2026 08:00:00 +0800</pubDate>
    <category>website update</category>
    <dc:creator>Shopify</dc:creator>
    <description>Compare Shopify's pricing plans to find the best fit for your business. Start your free trial today.</description>
    <enclosure url="https://cdn.shopify.com/assets/og-pricing.png" length="210000" type="image/png" />
  </item>

  <item>
    <title>Shopify: Enterprise Plus Solutions</title>
    <link>https://shopify.com/enterprise-plus</link>
    <guid isPermaLink="true">https://shopify.com/enterprise-plus</guid>
    <pubDate>Thu, 19 Feb 2026 11:20:00 +0800</pubDate>
    <category>website new page</category>
    <dc:creator>Shopify</dc:creator>
    <description>Unleash your brand's potential with Shopify Enterprise Plus. High-volume solutions for global commerce.</description>
    <enclosure url="https://cdn.shopify.com/assets/og-enterprise.jpg" length="320000" type="image/jpeg" />
  </item>

</channel>
</rss>

URL Parameters

Parameter Required Description Example
feed_id Yes The ID of the feed feed_abc123

Response Format

The response is a standard RSS 2.0 XML document. The structure is as follows:

Channel Elements

Element Description Example
<title> The feed name SaaS Competitors
<link> URL of the RSS feed https://nubela.co/api/v1/feeds/feed_abc123/rss.xml
<description> Auto-generated summary of monitored companies Automated updates for Stripe, Shopify, and Vercel.
<lastBuildDate> RFC 2822 timestamp of the last feed build Tue, 24 Feb 2026 10:00:00 +0800

Item Elements

Each <item> represents a single update from a monitored company.

Element Description Example
<title> Update title, prefixed with the company name Stripe: Expanding our Global Payment Network
<link> URL of the original content https://stripe.com/blog/global-network-2026
<guid> Unique identifier for the item. isPermaLink is true when the GUID is a URL. https://stripe.com/blog/global-network-2026
<pubDate> RFC 2822 publication timestamp Mon, 23 Feb 2026 14:30:00 +0800
<category> Update type (see categories below) blog
<dc:creator> Company name (uses Dublin Core namespace) Stripe
<description> Summary or excerpt of the update Text content
<enclosure> Optional image attachment with url, length (bytes), and type (MIME type) attributes <enclosure url="..." length="150000" type="image/jpeg" />

RSS Item Categories

Each <item> includes a <category> element indicating the update type:

Category Description
blog A new blog post from the company
x A post from the company's X (Twitter) account
website update A change detected on an existing page
website new page A new page detected on the company's website
website unreachable The company's website has become unreachable (fired once)

Error Codes

Status Code Charged? Description
403 No Missing or invalid token for a private feed
404 No Feed not found

Update Feed Endpoint

PATCH /api/v1/feeds/{feed_id}

Cost: 0 credits / request.

Update feed settings such as name, visibility, or suspension status. Feeds suspended for insufficient_credits are automatically resumed when credits are added.

# Suspend a feed
curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_suspended": true, "suspension_reason": "manual" }' \
  "https://nubela.co/api/v1/feeds/feed_abc123"

import requests

response = requests.patch(
    "https://nubela.co/api/v1/feeds/feed_abc123",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"is_suspended": True, "suspension_reason": "manual"},
)

const response = await fetch(
  "https://nubela.co/api/v1/feeds/feed_abc123",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ is_suspended: true, suspension_reason: "manual" }),
  }
);

Example response (same as Describe Feed):

{
  "id": "feed_abc123",
  "name": "My Feed",
  "is_public": false,
  "is_suspended": true,
  "suspension_reason": "manual",
  "rss_url": "https://nubela.co/api/v1/feeds/feed_abc123/rss.xml?token=...",
  "created_at": "2025-01-15T10:30:00Z",
  "targets": [...]
}

URL Parameters

Parameter Required Description Example
feed_id Yes The ID of the feed feed_abc123

Request Body

Parameter Required Description Example
name No New feed name "My Feed"
is_public No Whether the RSS feed is publicly accessible true
is_suspended No Set true to suspend, false to resume true
suspension_reason No Reason for suspension (only when is_suspended is true, default "manual") "manual"
email_notifications No Email notification mode. "on_updates" to receive emails when new updates are detected, "skip" to disable "on_updates"

At least one field must be provided.

Response

Returns the updated Feed Object with an additional targets array containing Target Object entries.

Error Codes

Status Code Charged? Description
400 No No valid fields provided
404 No Feed not found

Claude AI

NinjaPear provides an MCP (Model Context Protocol) server for direct integration with Claude. This allows you to query B2B company data conversationally — ask Claude about any company's customers, investors, employee count, and more.

Quick Start

  1. Get your connector string from the Dashboard
  2. Add NinjaPear as a connector in Claude (see setup instructions below)
  3. Start a new conversation and query B2B company data conversationally

Setup

Your connector string is available on the Dashboard. It looks like: https://nubela.co/mcp/sse?api_key=YOUR_API_KEY

Claude Platform (Recommended)

  1. Get your connector string from the Dashboard
  2. Make sure you're logged into Claude, then visit: Add Custom Connector
  3. Enter the following:
    • Name: NinjaPear
    • Remote MCP server URL: Paste your connector string from step 1
  4. Click Add connector
  5. Start a new conversation and ask Claude to use NinjaPear

Claude Code CLI

Get your connector string from the Dashboard, then run:

claude mcp add ninjapear --transport sse "YOUR_CONNECTOR_STRING"

Available Tools

Tool Description Cost
get_customer_listing Get customers, investors, and partners of a company 1 + 2/company
get_company_details Get company info, executives, financials 2-4 credits
get_employee_count Get employee count for a company 2 credits
check_disposable_email Check if email is disposable/free FREE
get_credit_balance Check your credit balance FREE
get_company_logo_url Get company logo URL FREE
list_feeds List all your monitoring feeds FREE
create_feed Create a new monitoring feed with targets 3 credits
describe_feed Get feed details with all targets FREE
update_feed Update feed name, visibility, or suspension FREE
delete_feed Delete a feed and all its targets FREE
add_target Add a company to monitor in a feed FREE
update_target Update monitoring settings for a target FREE
remove_target Remove a company from a feed FREE
consume_feed Read the latest updates from a feed FREE

Example Prompts

Once connected, you can ask Claude questions like:

Competitive Intelligence

You're a product manager tracking what your competitors are up to.

VC Portfolio Monitoring

You're a VC who wants to stay on top of portfolio company activity. Upload a CSV or screenshot of your portfolio companies to Claude, then ask:

Sales Prospecting

You're in sales and want to research accounts before outreach.

Market Research

You're an analyst mapping out an industry landscape.

Monitoring and Alerts

You want to set up ongoing monitoring and come back to check updates.

Account Management

Quick checks on your NinjaPear usage.

Error Handling

Errors are returned as descriptive messages that Claude will explain to you:

Error Message
Invalid API key "Error: 401 Unauthorized"
Insufficient credits "Error: 402 Payment Required"
Rate limited "Error: 429 Too Many Requests"
Server error "Error: 500 Internal Server Error"

Technical Details

MCP Protocol

The NinjaPear MCP server implements the Model Context Protocol specification, which is Anthropic's open standard for connecting AI assistants to external data sources and tools.

Transport

We use Server-Sent Events (SSE) transport for real-time communication:

Authentication

Pass your API key via the api_key query parameter or the X-API-Key header

cURL Python JavaScript