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 of any business globally.
2. (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 requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://nubela.co/api/v1/customer/listing",
    headers=headers
)

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.

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 / customer returned. Credits are charged even when the request returns an empty result.

Get a list of highly-probable customers of a target company.

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

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"website": "https://www.stripe.com"}
response = requests.get(
    "https://nubela.co/api/v1/customer/listing",
    headers=headers,
    params=params
)
print(response.json())

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",
      "id": "abc123",
      "industry": 45202030,
      "specialties": ["Technology", "Consumer Electronics"],
      "x_profile": "https://x.com/Apple"
    }
  ],
  "next_page": "https://nubela.co/api/v1/customer/listing?website=https://www.stripe.com&cursor=abc123"
}

URL Parameters

Response

CustomerCompany

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 requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://nubela.co/api/v1/meta/credit-balance",
    headers=headers
)
print(response.json())

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 requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"email": "[email protected]"}
response = requests.get(
    "https://nubela.co/api/v1/contact/disposable-email",
    headers=headers,
    params=params
)
print(response.json())

Example response:

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

URL Parameters

Response

Response Headers