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. (FREE TOOL) Retrieve the logo of any company.
3. (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();

• npm package
• GitHub repository

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

• PyPI package
• GitHub repository

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:

• PAYG plan: 2 requests/min
• $49/mo plan: 20 requests/min
• $299/mo plan: 50 requests/min
• $899/mo plan: 100 requests/min
• $1899/mo plan: 300 requests/min

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:

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:

• Adding attributes/parameters to API endpoints without prior notice.
• Adding additional response or requests headers to our API endpoints without prior notice.

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

Response

The API returns error 400 if we're not able to extract enough information about the target company.

CustomerCompany

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

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

Returns a 404 status code if no logo is found for the given domain.

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:

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

URL Parameters

Response

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

A 404 response is returned if no logo is found for the given domain.

Response Headers

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

Response Headers

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

Response

Response Headers