info:
  description: '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.


    As a data client of NinjaPear API, you can:

    1. Look up the customers, investors, and partners/platforms of any business globally.

    2. (FREE) Retrieve the logo of any company.

    3. (FREE) Find out the nature of an email address.

    4. (FREE) Check your credit balance.'
  contact:
    email: hello@nubela.co
  title: NinjaPear API
  version: 1.0.0
servers:
- url: https://nubela.co
  description: Production server
paths:
  /api/v1/customer/listing:
    get:
      summary: Customer Listing
      description: 'Get a list of highly-probable customers, investors, and partners/platforms
        of a target company, categorized by relationship type.


        **Cost:** 1 credit/request + 2 credits/company returned. Credits are charged
        even when the request returns an empty result.'
      operationId: getCustomerListing
      tags:
      - Customer API
      security:
      - bearerAuth: []
      parameters:
      - name: website
        in: query
        required: true
        description: The website URL of the target company
        schema:
          type: string
        example: https://www.stripe.com
      - name: cursor
        in: query
        required: false
        description: Pagination cursor from `next_page` in a previous response
        schema:
          type: string
      - name: page_size
        in: query
        required: false
        description: Number of results per page (1-200, default 200)
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 200
      - name: quality_filter
        in: query
        required: false
        description: Filter out low-quality results (junk TLDs and unreachable websites)
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Successful response with customer listing
          headers:
            X-NinjaPear-Credit-Cost:
              description: Total cost of credits for this API call
              schema:
                type: string
                example: '10'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerListingResponse'
        '400':
          description: Invalid parameters provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/company/logo:
    get:
      summary: Company Logo
      description: 'Retrieve the logo of a company given its website URL. Returns
        the logo as a PNG image (128x128).


        **Cost:** FREE (0 credits)'
      operationId: getCompanyLogo
      tags:
      - Company API
      security:
      - bearerAuth: []
      parameters:
      - name: website
        in: query
        required: true
        description: The website URL of the target company
        schema:
          type: string
        example: https://www.stripe.com
      responses:
        '200':
          description: Company logo as PNG image
          headers:
            X-NinjaPear-Credit-Cost:
              description: Total cost of credits for this API call
              schema:
                type: string
                example: '0'
          content:
            image/png:
              schema:
                type: string
                format: binary
        '404':
          description: No logo found for the given domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Invalid parameters provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/meta/credit-balance:
    get:
      summary: View Credit Balance
      description: 'Get your current credit balance.


        **Cost:** FREE (0 credits)'
      operationId: getCreditBalance
      tags:
      - Meta API
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Current credit balance
          headers:
            X-NinjaPear-Credit-Cost:
              description: Total cost of credits for this API call
              schema:
                type: string
                example: '0'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalanceResponse'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/contact/disposable-email:
    get:
      summary: Disposable Email Checker
      description: 'Check if an email address is a disposable (temporary/throwaway)
        email or a free email provider.


        **Cost:** FREE (0 credits)'
      operationId: checkDisposableEmail
      tags:
      - Contact API
      security:
      - bearerAuth: []
      parameters:
      - name: email
        in: query
        required: true
        description: The email address to check
        schema:
          type: string
          format: email
        example: test@mailinator.com
      responses:
        '200':
          description: Email check result
          headers:
            X-NinjaPear-Credit-Cost:
              description: Total cost of credits for this API call
              schema:
                type: string
                example: '0'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisposableEmailResponse'
        '400':
          description: Invalid parameters provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/company/details:
    get:
      summary: Company Details
      description: 'Retrieve detailed company information including description, industry,
        executives, addresses, and for public companies: financials and stock info.


        **Cost:** 2 credits (4 credits if include_employee_count=true)'
      operationId: getCompanyDetails
      tags:
      - Company API
      security:
      - bearerAuth: []
      parameters:
      - name: website
        in: query
        required: true
        description: The website URL of the target company
        schema:
          type: string
        example: https://www.stripe.com
      - name: include_employee_count
        in: query
        required: false
        description: Fetch fresh employee count data via web search. Adds 2 credits.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Company details
          headers:
            X-NinjaPear-Credit-Cost:
              description: Total cost of credits for this API call
              schema:
                type: string
                example: '2'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyDetailsResponse'
        '404':
          description: No company data found for the given website
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Invalid parameters provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/company/employee-count:
    get:
      summary: Employee Count
      description: 'Get the employee count for a company. Uses web search to find
        the most recent employee count information.


        **Cost:** 2 credits'
      operationId: getEmployeeCount
      tags:
      - Company API
      security:
      - bearerAuth: []
      parameters:
      - name: website
        in: query
        required: true
        description: The website URL of the target company
        schema:
          type: string
        example: https://www.stripe.com
      responses:
        '200':
          description: Employee count data
          headers:
            X-NinjaPear-Credit-Cost:
              description: Total cost of credits for this API call
              schema:
                type: string
                example: '2'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeCountResponse'
        '404':
          description: No employee count data found for the given website
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Invalid parameters provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
openapi: 3.0.3
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Invalid API Key
    CustomerCompany:
      type: object
      properties:
        name:
          type: string
          description: Company name
          example: Apple
        description:
          type: string
          nullable: true
          description: A brief description of the company
          example: Apple Inc. designs, manufactures, and markets smartphones...
        tagline:
          type: string
          nullable: true
          description: Company tagline or slogan
          example: Think different.
        website:
          type: string
          nullable: true
          description: Company website URL
          example: https://www.apple.com
        company_logo_url:
          type: string
          nullable: true
          description: URL to the Company Logo API for this company
          example: https://nubela.co/api/v1/company/logo?website=https%3A%2F%2Fwww.apple.com
        id:
          type: string
          description: Unique identifier
          example: abc123
        industry:
          type: integer
          nullable: true
          description: GICS 8-digit industry code
          example: 45202030
        specialties:
          type: array
          items:
            type: string
          nullable: true
          description: List of company specialties
          example:
          - Technology
          - Consumer Electronics
        x_profile:
          type: string
          nullable: true
          description: X (Twitter) profile URL
          example: https://x.com/Apple
    CustomerListingResponse:
      type: object
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCompany'
          description: Companies that are probable customers of the target company
        investors:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCompany'
          description: VC firms, PE funds, angel networks that have invested in the
            target company
        partner_platforms:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCompany'
          description: Partners, platforms, or service providers the target company
            uses
        next_page:
          type: string
          nullable: true
          description: Pagination URL for the next page of results
          example: https://nubela.co/api/v1/customer/listing?website=https://www.stripe.com&cursor=abc123
    CreditBalanceResponse:
      type: object
      properties:
        credit_balance:
          type: integer
          description: Your current credit balance
          example: 100000
    DisposableEmailResponse:
      type: object
      properties:
        email:
          type: string
          description: The email address that was checked
          example: test@mailinator.com
        is_disposable_email:
          type: boolean
          description: Whether the email domain is a known disposable/temporary email
            provider
          example: true
        is_free_email:
          type: boolean
          description: Whether the email domain is a free email provider
          example: false
    EmployeeCountResponse:
      type: object
      properties:
        employee_count:
          type: integer
          description: Estimated employee count
          example: 3500
    Address:
      type: object
      properties:
        address_type:
          type: string
          description: Type of address
          enum:
          - HEADQUARTERS
          - REGISTERED
          - BRANCH
          - MAILING
          - OTHER
          example: HEADQUARTERS
        line1:
          type: string
          nullable: true
          description: Street address line 1
          example: 354 Oyster Point Blvd
        line2:
          type: string
          nullable: true
          description: Street address line 2
        city:
          type: string
          nullable: true
          description: City name
          example: South San Francisco
        state:
          type: string
          nullable: true
          description: State, province, or region
          example: CA
        postal_code:
          type: string
          nullable: true
          description: Postal/ZIP code
          example: '94080'
        country_code:
          type: string
          nullable: true
          description: ISO 3166-1 alpha-2 country code
          example: US
        country:
          type: string
          nullable: true
          description: Full country name
          example: United States
        is_primary:
          type: boolean
          description: Whether this is the primary address
          example: true
    Executive:
      type: object
      properties:
        name:
          type: string
          description: Full name of the executive
          example: Patrick Collison
        title:
          type: string
          nullable: true
          description: Job title
          example: Chief Executive Officer
        role:
          type: string
          nullable: true
          description: Normalized role type
          enum:
          - CEO
          - CFO
          - COO
          - CTO
          - CMO
          - PRESIDENT
          - VICE_PRESIDENT
          - DIRECTOR
          - BOARD_MEMBER
          - CHAIRMAN
          - FOUNDER
          - OTHER
          example: CEO
    PublicListing:
      type: object
      description: Public company financial data. Only present for public companies.
      properties:
        stock_symbol:
          type: string
          nullable: true
          description: Stock ticker symbol
          example: AAPL
        ipo_date:
          type: string
          nullable: true
          description: IPO date in ISO format
          example: '1980-12-12'
        isin:
          type: string
          nullable: true
          description: International Securities Identification Number
          example: US0378331005
        figi:
          type: string
          nullable: true
          description: Financial Instrument Global Identifier
          example: BBG000B9XRY4
        cusip:
          type: string
          nullable: true
          description: CUSIP identifier
          example: 037833100
        lei:
          type: string
          nullable: true
          description: Legal Entity Identifier
          example: HWUPKR0MPOU8FGXBT394
        cik:
          type: string
          nullable: true
          description: SEC Central Index Key
          example: 0000320193
        sic_code:
          type: string
          nullable: true
          description: SEC Standard Industrial Classification code
          example: '3571'
        revenue_usd:
          type: integer
          nullable: true
          description: Annual revenue in USD
          example: 383285000000
        revenue_captured_at:
          type: string
          nullable: true
          description: Date when revenue data was captured (ISO format)
          example: '2024-09-28'
        ebitda_usd:
          type: integer
          nullable: true
          description: EBITDA in USD
          example: 134000000000
        ebitda_captured_at:
          type: string
          nullable: true
          description: Date when EBITDA data was captured (ISO format)
          example: '2024-09-28'
    CompanyDetailsResponse:
      type: object
      properties:
        websites:
          type: array
          items:
            type: string
          nullable: true
          description: List of all company website URLs
          example:
          - https://stripe.com
          - https://stripe.dev
        description:
          type: string
          nullable: true
          description: A brief description of the company
          example: Stripe is a technology company that builds economic infrastructure
            for the internet.
        industry:
          type: integer
          nullable: true
          description: GICS 8-digit industry code
          example: 45102010
        company_type:
          type: string
          nullable: true
          description: Type of company
          enum:
          - PUBLIC_COMPANY
          - PRIVATELY_HELD
          - GOVERNMENT_AGENCY
          - NON_PROFIT
          - EDUCATIONAL
          - PARTNERSHIP
          - SELF_EMPLOYED
          - SELF_OWNED
          example: PRIVATELY_HELD
        founded_year:
          type: integer
          nullable: true
          description: Year the company was founded
          example: 2010
        specialties:
          type: array
          items:
            type: string
          nullable: true
          description: List of company specialties
          example:
          - Payments
          - Financial Services
          - APIs
        name:
          type: string
          nullable: true
          description: Company name
          example: Stripe
        tagline:
          type: string
          nullable: true
          description: Company tagline or slogan
          example: Financial infrastructure for the internet
        logo_url:
          type: string
          nullable: true
          description: URL to the company logo endpoint
          example: https://nubela.co/api/v1/company/logo?website=https://stripe.com
        cover_pic_url:
          type: string
          nullable: true
          description: URL to the company's cover/banner image
        facebook_url:
          type: string
          nullable: true
          description: Facebook profile URL
          example: https://facebook.com/stripe
        twitter_url:
          type: string
          nullable: true
          description: Twitter/X profile URL
          example: https://twitter.com/stripe
        instagram_url:
          type: string
          nullable: true
          description: Instagram profile URL
        employee_count:
          type: integer
          nullable: true
          description: Estimated number of employees
          example: 8000
        employee_count_range_min:
          type: integer
          nullable: true
          description: Lower bound of employee count range (only with include_employee_count=true)
          example: 7500
        employee_count_range_max:
          type: integer
          nullable: true
          description: Upper bound of employee count range (only with include_employee_count=true)
          example: 8500
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          nullable: true
          description: List of company addresses
        executives:
          type: array
          items:
            $ref: '#/components/schemas/Executive'
          nullable: true
          description: List of company executives and board members
        public_listing:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/PublicListing'
          description: Public company data. Null for private companies.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication via Bearer token. Get your API key from
        the API section in the dashboard at https://nubela.co/dashboard
