> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate NPNs

> Look up National Producer Numbers via NIPR to determine if they belong to an agency (firm), agent (individual), or are not found

Accepts an array of 1–20 National Producer Numbers and returns NIPR data for each, indicating whether the NPN belongs to a firm (agency), individual (agent), or is not found.

Duplicate NPNs in the request body are deduplicated before lookup. Results are returned for the unique set of NPNs only.

Only one request per account can be in progress at a time. If you send a second request while the first is still processing, you will receive a `429 Too Many Requests` error.


## OpenAPI

````yaml openapi/v1.json POST /v1/npn-lookup
openapi: 3.0.0
info:
  title: Turris Public API
  description: API for managing insurance compliance data
  version: 1.0.0
  contact: {}
servers:
  - url: https://public.api.live.turrisfi.com
    description: Production
  - url: https://public.api.sandbox.turrisfi.com
    description: Sandbox
security: []
tags: []
paths:
  /v1/npn-lookup:
    post:
      tags:
        - npn-lookup
      summary: Look up NPNs via NIPR
      description: >-
        Accepts an array of 1–20 National Producer Numbers and returns NIPR data
        for each, indicating whether the NPN belongs to a firm (agency),
        individual (agent), or is not found. Only one request per account can be
        in progress at a time.
      operationId: NpnLookupController_lookupNpns_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NpnLookupDto'
      responses:
        '200':
          description: Array of NPN lookup results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NpnLookupResultItemResponse'
                  requestId:
                    type: string
                    description: Unique request identifier
                    example: dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8
                  timestamp:
                    type: string
                    description: Response timestamp
                    example: '2025-11-12T20:49:03.293Z'
                required:
                  - data
                  - requestId
                  - timestamp
        '400':
          description: >-
            Invalid request body — NPNs must be an array of 1–20 digit-only
            strings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Invalid or missing auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: A lookup request is already in progress for this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
components:
  schemas:
    NpnLookupDto:
      type: object
      properties:
        npns:
          description: Array of National Producer Numbers to look up
          example:
            - '1234567'
            - '9876543'
          minItems: 1
          maxItems: 20
          type: array
          items:
            type: string
      required:
        - npns
    NpnLookupResultItemResponse:
      type: object
      properties:
        npn:
          type: string
          description: National Producer Number
          example: '1234567'
        entityType:
          type: string
          description: The type of entity associated with this NPN
          enum:
            - individual
            - firm
            - not found
            - error
          example: individual
        name:
          type: string
          description: Name of the individual or firm
          example: John Doe
        residentStates:
          description: States where the entity holds a resident license
          example:
            - CA
            - TX
          type: array
          items:
            type: string
        fein:
          type: string
          description: Federal Employer Identification Number (firms only)
          example: 12-3456789
        dateOfBirth:
          type: string
          description: Date of birth (individuals only)
          example: 01/01/1990
        error:
          type: string
          description: Error message if the lookup failed for this NPN
      required:
        - npn
        - entityType
    ErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
        requestId:
          type: string
          description: Unique request identifier for debugging
        errorType:
          type: string
          description: Error type classification
        errorMessage:
          description: Array of error messages
          type: array
          items:
            type: string
        timestamp:
          type: string
          description: ISO timestamp when the error occurred
        details:
          type: object
          description: Additional error context
      required:
        - statusCode
        - requestId
        - errorType
        - errorMessage
        - timestamp

````