api-ninjas-com NAICS Code API

openapi: 3.2.0
info:
  title: Ninjas NAICS Code API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: NAICS Code
  description: 'Look up any North American Industry Classification System (NAICS) 2022 code: official title, description, full hierarchy, over 20,000 official Census index terms and the official cross-reference rules, plus a crosswalk to NAICS 2017. Adds the SBA small-business size standard for a code (13 CFR 121.201), rule-based classification of a business description to a single defensible code, and an industry risk profile for KYB and underwriting screening.


    NAICS is a work of the U.S. Government and is in the public domain under 17 U.S.C. 105. API Ninjas is not affiliated with, endorsed by, or sponsored by the U.S. Census Bureau, the U.S. Office of Management and Budget, or the U.S. Small Business Administration.


    Size-standard results are informational and are not SBA size determinations. The risk profile describes an industry, never a specific business; it is not a compliance determination, not a consumer report, and must not be the sole basis for denying service to a business.'
paths:
  /v1/naics:
    get:
      tags:
      - NAICS Code
      summary: Look up a NAICS code
      operationId: getNaics
      description: Returns the official title, description, full hierarchy, index terms and cross-references for a NAICS code. Pass crosswalk_to to also map the code to another NAICS revision or to SIC. Available on all plans.
      parameters:
      - $ref: '#/components/parameters/NaicsCodeOpenapi_code'
      - $ref: '#/components/parameters/codes'
      - $ref: '#/components/parameters/title'
      - $ref: '#/components/parameters/NaicsCodeOpenapi_year'
      - $ref: '#/components/parameters/NaicsCodeOpenapi_country'
      - $ref: '#/components/parameters/crosswalk_to'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCode'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '403':
          description: Endpoint or field requires a higher subscription tier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/naicssearch:
    get:
      tags:
      - NAICS Code
      summary: Search NAICS codes by keyword
      operationId: searchNaics
      description: Ranked candidate codes for a keyword or phrase, matched against over 20,000 official Census index terms plus titles and descriptions. Returns every plausible code without applying classification rules. Available on all plans; results capped at 5 on Free and Learner.
      parameters:
      - $ref: '#/components/parameters/query'
      - $ref: '#/components/parameters/NaicsCodeOpenapi_year'
      - $ref: '#/components/parameters/NaicsCodeOpenapi_level'
      - $ref: '#/components/parameters/NaicsCodeOpenapi_limit'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_SearchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '403':
          description: Endpoint or field requires a higher subscription tier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/naicssizestandard:
    get:
      tags:
      - NAICS Code
      summary: SBA small-business size standard for a NAICS code
      operationId: getNaicsSizeStandard
      description: Returns the SBA size standard from 13 CFR 121.201 for a code, and a small-business eligibility verdict when revenue or employees is supplied. Requires a Developer subscription or above; calculation basis, affiliation notes and exceptions require Business or above.
      parameters:
      - $ref: '#/components/parameters/NaicsCodeOpenapi_code'
      - $ref: '#/components/parameters/codes'
      - $ref: '#/components/parameters/revenue'
      - $ref: '#/components/parameters/employees'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SizeStandardResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '403':
          description: Endpoint or field requires a higher subscription tier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/naicsclassify:
    get:
      tags:
      - NAICS Code
      summary: Classify a business description to a single NAICS code
      operationId: classifyNaics
      description: 'Assigns one primary NAICS code to a business description by applying NAICS classification rules: the primary-activity test, cross-reference exclusions, and establishment scope. Returns the deciding rule and supporting evidence for audit. Requires a Business subscription or above.'
      parameters:
      - $ref: '#/components/parameters/description'
      - $ref: '#/components/parameters/NaicsCodeOpenapi_year'
      - $ref: '#/components/parameters/include_alternatives'
      - $ref: '#/components/parameters/min_confidence'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifyResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '403':
          description: Endpoint or field requires a higher subscription tier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/naicsrisk:
    get:
      tags:
      - NAICS Code
      summary: Industry risk profile for a NAICS code
      operationId: getNaicsRisk
      description: Returns a KYB and underwriting risk profile for an industry, including money-services, cash-intensive, cannabis, firearms, gambling and crypto flags, typical merchant category codes, and a review recommendation. Informational only, not a compliance determination. Requires a Business subscription or above.
      parameters:
      - $ref: '#/components/parameters/NaicsCodeOpenapi_code'
      - $ref: '#/components/parameters/codes'
      - $ref: '#/components/parameters/framework'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '403':
          description: Endpoint or field requires a higher subscription tier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaicsCodeOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
components:
  parameters:
    crosswalk_to:
      name: crosswalk_to
      in: query
      required: false
      schema:
        type: string
        enum:
        - '2017'
      example: '2027'
      description: Also map the code to an earlier NAICS revision. Currently 2017 only. The Census concordance covers 6-digit national industries.
    employees:
      name: employees
      in: query
      required: false
      schema:
        type: integer
      example: 120
      description: Employee count. Used when the size standard for the code is employee-based.
    query:
      name: query
      in: query
      required: true
      schema:
        type: string
      example: mobile app development
      description: Keyword or phrase describing an industry or activity. Limited to 300 characters; for a full business description use /naicsclassify.
    NaicsCodeOpenapi_limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 25
        default: 5
      example: 5
      description: Maximum results. Capped at 5 on Free and Learner, 25 on Developer and above.
    framework:
      name: framework
      in: query
      required: false
      schema:
        type: string
        enum:
        - kyb
        - card
        - lending
        default: kyb
      example: kyb
      description: Risk lens to apply.
    codes:
      name: codes
      in: query
      required: false
      schema:
        type: string
      example: 541511,541512,238350
      description: Comma-separated NAICS codes for batch lookup. Maximum 50 on Developer, 500 on Business and above.
    min_confidence:
      name: min_confidence
      in: query
      required: false
      schema:
        type: number
        minimum: 0
        maximum: 1
      example: 0.5
      description: Suppress results below this confidence.
    include_alternatives:
      name: include_alternatives
      in: query
      required: false
      schema:
        type: boolean
        default: true
      example: true
      description: Include rejected candidate codes and the rule that rejected each.
    description:
      name: description
      in: query
      required: true
      schema:
        type: string
      example: We manufacture kitchen cabinets and also install them in customers' homes.
      description: Free-text description of the business or establishment to classify. Limited to 2000 characters.
    NaicsCodeOpenapi_code:
      name: code
      in: query
      required: false
      schema:
        type: string
      example: '541511'
      description: NAICS code, 2 to 6 digits. Required unless title is provided.
    NaicsCodeOpenapi_country:
      name: country
      in: query
      required: false
      schema:
        type: string
        enum:
        - US
        default: US
      example: US
      description: Currently US only. NAICS Canada and SCIAN Mexico are not yet available.
    NaicsCodeOpenapi_year:
      name: year
      in: query
      required: false
      schema:
        type: string
        enum:
        - '2022'
        default: '2022'
      example: '2022'
      description: NAICS revision. Currently 2022 only; NAICS 2027 is not published by the Census Bureau until January 2027.
    NaicsCodeOpenapi_level:
      name: level
      in: query
      required: false
      schema:
        type: integer
        minimum: 2
        maximum: 6
      example: 6
      description: Restrict results to codes of this digit length.
    revenue:
      name: revenue
      in: query
      required: false
      schema:
        type: number
      example: 18000000
      description: Annual receipts in USD. When supplied, the response includes a small-business eligibility verdict.
    title:
      name: title
      in: query
      required: false
      schema:
        type: string
      example: Custom Computer Programming
      description: Look up by official title. Supports partial matching.
  schemas:
    CrossReference:
      type: object
      properties:
        text:
          type: string
        code:
          type:
          - string
          - 'null'
    ClassifyResponse:
      type: object
      properties:
        input:
          type: string
        primary:
          type: object
          properties:
            code:
              type: string
            title:
              type: string
            confidence:
              type: number
            decided_by:
              type: string
        secondary_codes:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              title:
                type: string
              activity:
                type: string
              ancillary:
                type: boolean
        adjudication:
          type: object
          properties:
            candidates_considered:
              type: integer
            rules_applied:
              type: array
              items:
                $ref: '#/components/schemas/ClassifyRule'
            evidence:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  text:
                    type: string
                  similarity:
                    type: number
        establishment_note:
          type:
          - string
          - 'null'
        alternatives:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              title:
                type: string
              confidence:
                type: number
              rejected_by:
                type: string
        classified_at:
          type: string
          format: date-time
        data_as_of:
          type: string
        retrieved_at:
          type: string
          format: date-time
        source:
          type: string
        disclaimer:
          type: object
          additionalProperties:
            type: string
    ClassifyRule:
      type: object
      properties:
        rule:
          type: string
          enum:
          - primary_activity
          - cross_reference_exclusion
          - establishment_scope
        code:
          type:
          - string
          - 'null'
        source_text:
          type:
          - string
          - 'null'
        outcome:
          type:
          - string
          - 'null'
          enum:
          - excluded
          - not_excluded
          - null
        detail:
          type: string
    SearchResult:
      type: object
      properties:
        code:
          type: string
        title:
          type: string
        score:
          type: number
        matched_on:
          type: string
          enum:
          - index_term
          - title
          - description
        matched_text:
          type: string
    NaicsCodeOpenapi_ErrorResponse:
      type: object
      properties:
        error:
          type: string
    NaicsCodeOpenapi_SearchResponse:
      type: object
      properties:
        query:
          type: string
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
        data_as_of:
          type: string
        retrieved_at:
          type: string
          format: date-time
        source:
          type: string
        disclaimer:
          type: object
          additionalProperties:
            type: string
    HierarchyLevel:
      type: object
      properties:
        code:
          type: string
        level:
          type: integer
        title:
          type: string
    SizeStandardResponse:
      type: object
      properties:
        code:
          type: string
        title:
          type: string
        size_standard:
          type: object
          properties:
            basis:
              type: string
              enum:
              - annual_receipts
              - employees
            threshold_usd:
              type:
              - number
              - 'null'
            threshold_employees:
              type:
              - integer
              - 'null'
        eligibility:
          type:
          - object
          - 'null'
          properties:
            is_small:
              type: boolean
            evaluated_on:
              type: string
            your_value:
              type: number
            headroom_usd:
              type:
              - number
              - 'null'
            headroom_pct:
              type:
              - number
              - 'null'
        footnotes:
          type: array
          items:
            type: string
        calculation_basis:
          type: string
          description: Premium. Business tier and above.
        affiliation_note:
          type: string
          description: Premium. Business tier and above.
        exceptions:
          type: array
          items:
            type: string
          description: Premium. Business tier and above.
        authority:
          type: string
          example: 13 CFR 121.201
        effective_date:
          type: string
          format: date
        data_as_of:
          type: string
        retrieved_at:
          type: string
          format: date-time
        source:
          type: string
        disclaimer:
          type: object
          additionalProperties:
            type: string
    NaicsCode:
      type: object
      properties:
        code:
          type: string
        title:
          type: string
        level:
          type: integer
        level_name:
          type: string
          enum:
          - sector
          - subsector
          - industry_group
          - industry
          - national_industry
        year:
          type: integer
        country:
          type: string
        description:
          type: string
        hierarchy:
          type: array
          items:
            $ref: '#/components/schemas/HierarchyLevel'
        parent:
          type:
          - string
          - 'null'
        children:
          type: array
          items:
            type: string
        index_terms:
          type: array
          items:
            type: string
        index_term_count:
          type: integer
        cross_references:
          type: array
          items:
            $ref: '#/components/schemas/CrossReference'
        changes_in_2027:
          type: object
          properties:
            status:
              type: string
            notes:
              type:
              - string
              - 'null'
        crosswalk:
          $ref: '#/components/schemas/Crosswalk'
        data_as_of:
          type: string
        retrieved_at:
          type: string
          format: date-time
        source:
          type: string
        disclaimer:
          type: object
          additionalProperties:
            type: string
        pointers:
          type: array
          items:
            type: string
          description: Census '******' pointer entries, surfaced by /naicssearch when nothing else matched.
    RiskResponse:
      type: object
      properties:
        code:
          type: string
        title:
          type: string
        risk_level:
          type: string
          enum:
          - low
          - moderate
          - high
        flags:
          type: object
          additionalProperties:
            type: boolean
        rationale:
          type: array
          items:
            type: string
        typical_mcc:
          type: array
          items:
            type: string
        commonly_prohibited_by:
          type: array
          items:
            type: string
        review_recommendation:
          type: string
          enum:
          - standard
          - enhanced_due_diligence
          - decline_typical
        data_as_of:
          type: string
        retrieved_at:
          type: string
          format: date-time
        source:
          type: string
        disclaimer:
          type: object
          additionalProperties:
            type: string
    Crosswalk:
      type: object
      properties:
        to:
          type: string
        change_type:
          type: string
          enum:
          - unchanged
          - renamed
          - split
          - merged
          - new
          - discontinued
        mappings:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              title:
                type: string
              share:
                type:
                - number
                - 'null'
        note:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api