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

# Add NPN

> Add an NPN to an agency that was added without one

Adds an NPN to an agency you added with [Add](https://docs.turrisfi.com/api-reference/v2/downstream-entity-associations/add.md) before you had its NPN. Turris looks the NPN up in NIPR, sets the agency's legal name from NIPR, and sets up its compliance data subscription, the same as an Add with an NPN. The response is the full association, identical in shape to [Get Association](https://docs.turrisfi.com/api-reference/v2/downstream-entity-associations/get-association.md).

## What happens next

If your organization has auto-sync on, the agency's first sync is queued straight away, as it would be after an Add with an NPN. Otherwise call [Sync Downstream Entity](https://docs.turrisfi.com/api-reference/v2/compliance-data-subscriptions/sync-downstream-entity.md) when you are ready. A first sync can wait for NIPR's overnight update; that page explains when.

If you already monitor this NPN through another of your agencies, the agency shares that subscription. When that subscription has already synced, the license data is already there and Sync Downstream Entity answers `409`.

## When it is refused

Every refusal happens before anything is written.

| Status | When |
| - | - |
| `400` | The NPN is not 1 to 10 digits |
| `404` | The association is not one of yours, or is archived |
| `404` | NIPR has no agency with that NPN |
| `409` | The agency already has an NPN. Changing an NPN is not supported through the API |
| `409` | The agency manages its own Turris account |
| `409` | Your compliance data subscription for that NPN is paused. Contact support to restore it |
| `503` | The NIPR lookup failed. Try again shortly |

Send an `Idempotency-Key` header to retry safely: a repeated request with the same key returns the original response instead of `409`.

> [!NOTE]
>
> **Sandbox:** NPN data in sandbox is limited and scrambled. Turris looks the NPN up as an agency, so an NPN that sandbox data records as an individual returns `404`, even when it is a real agency NPN.


## OpenAPI

````yaml openapi/v2.json POST /v2/upstream/downstream-entity-associations/{downstreamEntityAssociationId}/npn
openapi: 3.0.0
info:
  title: Turris Public API
  description: API for managing insurance compliance data
  version: 2.0.0
  contact: {}
servers:
  - url: https://public.api.live.turrisfi.com
    description: Production
  - url: https://public.api.sandbox.turrisfi.com
    description: Sandbox
security:
  - bearer: []
  - restricted-access-token: []
tags:
  - name: auth
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: downstream/actions-required
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/appointments
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/carriers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/compliance-configs
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/contacts
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/corporate-registrations
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/documents
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/entities
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-overview
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-requests
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/licenses
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/markets
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/producers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-filings
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-states
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: heartbeat
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: upstream/agents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/agents-license-compliance
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/appointment-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/carriers
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/compliance-data-subscriptions
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contract-container-templates
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/diligent-effort-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/downstream-entity-associations
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/file-documents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/market-contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/npn-lookup
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/policies
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/products
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-filings
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-states
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/termination-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/webhooks
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
paths:
  /v2/upstream/downstream-entity-associations/{downstreamEntityAssociationId}/npn:
    post:
      tags:
        - upstream/downstream-entity-associations
      summary: Add an NPN
      description: >-
        Adds an NPN to an agency that was added without one, and sets up its
        compliance data subscription so the agency can then be synced. Refused
        when the agency already has an NPN.
      operationId: AssociatedDownstreamEntitiesV2Controller_addDownstreamEntityNpn_v2
      parameters:
        - name: downstreamEntityAssociationId
          required: true
          in: path
          description: Downstream entity association ID
          schema:
            example: 507f1f77bcf86cd799439011
            type: string
        - name: idempotency-key
          in: header
          description: UUID to ensure idempotent request processing
          required: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
        - name: x-idempotency-key
          in: header
          description: Alternative UUID header for idempotent request processing
          required: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddDownstreamEntityNpnDto'
      responses:
        '200':
          description: >-
            The association, now carrying the NPN, the legal name from NIPR and
            the compliance data subscription
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: >-
                      #/components/schemas/DownstreamEntityAssociationWithHierarchyResponseDto
                  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: The NPN is not 1 to 10 digits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Invalid or missing auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: >-
            Returned with `errorType` `invalid_organization_category` when your
            credential's organization category does not match the one this
            endpoint serves; `details` names the expected and actual category.
            This endpoint can return 403 for other reasons too, so branch on
            `errorType`; the Error Handling guide lists them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: >-
            Downstream entity association not found, or NIPR has no agency with
            that NPN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '409':
          description: >-
            The agency already has an NPN, manages its own Turris account, or
            the NPN's compliance data subscription is paused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: >-
            Too many requests: this credential passed the API-wide limit of 1000
            requests per 10 seconds, counted across every endpoint. The request
            was not processed. Wait the number of seconds in the Retry-After
            header, then retry.
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Sent when a rate limit refused
                the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '503':
          description: The NIPR lookup failed; try again
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
components:
  schemas:
    AddDownstreamEntityNpnDto:
      type: object
      properties:
        npn:
          type: string
          description: >-
            The agency's National Producer Number (NPN), 1 to 10 digits. Leading
            zeros are dropped when it is stored.
          example: '12345678'
      required:
        - npn
    DownstreamEntityAssociationWithHierarchyResponseDto:
      type: object
      properties:
        _id:
          type: string
          description: Association ID
        producerCode:
          type: string
          description: Producer code
        externalId:
          type: string
          description: External ID
        branchName:
          type: string
          description: Branch or office name for this association
        creationPath:
          type: string
          description: >-
            How this association was created: invitation, addition, bulk-upload,
            market, or hubspot sync. Immutable once set.
        isNpnRequired:
          type: boolean
          description: >-
            Whether your organization requires this downstream entity's NPN for
            this relationship. You set it when you add or invite the entity; it
            decides whether compliance is evaluated on the entity's own licenses
            or on its producers'.
        downstreamEntity:
          description: Downstream entity details
          allOf:
            - $ref: '#/components/schemas/PopulatedDownstreamEntityResponse'
        niprDataSubscription:
          description: NIPR data subscription for this association
          allOf:
            - $ref: '#/components/schemas/ComplianceDataSubscriptionResponse'
        path:
          type: string
          description: >-
            Materialized ancestor chain, "/rootId/parentId/currentId". Segments
            are association ids, so each one can be looked up through this same
            endpoint. A top-level agency is "/ownId". Snapshot: moving an agency
            to a different parent rewrites it. In the rare case where an
            association has no stored path, this is synthesized as "/ownId" so
            the field is always present.
        level:
          type: number
          description: Depth in the hierarchy. 0 is a top-level agency.
        parentAssociationId:
          type: string
          description: >-
            Immediate parent association id. Null for a top-level agency, never
            absent.
          nullable: true
        ultimateParentAssociationId:
          type: string
          description: >-
            First segment of path. A top-level agency is its own ultimate
            parent.
        ultimateParentAgreementExecuted:
          type: boolean
          description: >-
            Whether the ultimate parent has an executed producer agreement.
            Always refers to the ROOT of the chain, never to the nearest
            ancestor that happens to have signed; at depth two those coincide.
            Snapshot as of this response.
        entityType:
          type: string
          description: Your record of the agency's legal structure. Absent when never set.
          enum:
            - C-Corp
            - LLC
            - Partnership
            - S-Corp
            - Sole Proprietor
          example: LLC
        legalAddress:
          description: Your record of the agency's legal address. Absent when never set.
          allOf:
            - $ref: '#/components/schemas/AssociationAddressResponse'
        mailingAddress:
          description: Your record of the agency's mailing address. Absent when never set.
          allOf:
            - $ref: '#/components/schemas/AssociationAddressResponse'
        doingBusinessAs:
          type: string
          description: >-
            Your record of the agency's doing-business-as name. Absent when
            never set.
          example: Example Insurance Agency
        website:
          type: string
          description: Your record of the agency's website. Absent when never set.
          example: https://www.example-agency.com
        phoneNumber:
          type: string
          description: >-
            Your record of the agency's phone number. Absent when never set. A
            number written through Update Association is in the form +1 (215)
            555-0100; one entered elsewhere is returned as stored.
          example: +1 (215) 555-0100
        faxNumber:
          type: string
          description: >-
            Your record of the agency's fax number. Absent when never set. Same
            form as phoneNumber.
          example: +1 (215) 555-0101
      required:
        - _id
        - isNpnRequired
        - downstreamEntity
        - niprDataSubscription
        - path
        - level
        - parentAssociationId
        - ultimateParentAssociationId
        - ultimateParentAgreementExecuted
    ErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
        requestId:
          type: string
          description: Unique request identifier for debugging
        errorType:
          type: string
          description: >-
            Machine-readable error classification. Branch on this rather than on
            `errorMessage`, which is prose and may change. Authentication
            failures returned by our identity provider are forwarded verbatim,
            so a 401 can carry a code outside this list; treat an unrecognised
            value as a generic failure of its HTTP status.
          enum:
            - conflict
            - contact_not_authorized
            - contract_already_signed
            - document_exceeds_page_limit
            - downstream_entity_member_exists
            - duplicate_external_id_error
            - duplicate_member_email
            - duplicate_producer_code_error
            - forbidden
            - gateway_timeout
            - inactive_email
            - internal_server_error
            - invalid_email
            - invalid_email_for_invites
            - invalid_organization_category
            - invalid_organization_slug
            - invalid_phone_number
            - invalid_token
            - invite_limit_reached
            - jwt_invalid
            - m2m_client_not_found
            - not_found
            - online_signing_in_progress
            - organization_already_exists
            - organization_slug_already_used
            - payment_required
            - producer_agreement_required
            - product_feature_subscription_required
            - service_unavailable
            - session_authorization_error
            - some_custom_error_string
            - throttled
            - too_many_requests
            - unauthorized
            - unauthorized_client
            - unexpected_400_stytch_error
            - unexpected_403_stytch_error
            - unexpected_404_stytch_error
            - unexpected_error
            - unexpected_stytch_error
            - unprocessable_entity
            - validation_error
          example: validation_error
        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
    PopulatedDownstreamEntityResponse:
      type: object
      properties:
        _id:
          type: string
          description: Downstream entity ID
        isNpnRequired:
          type: boolean
          description: >-
            Same value as the association's `isNpnRequired`, kept for
            compatibility. Read the top-level field.
        legalName:
          type: string
          description: Legal name of the downstream entity
        category:
          type: string
          description: Category of the downstream entity
        npn:
          type: string
          description: National Producer Number
        ein:
          type: string
          description: Employer Identification Number
      required:
        - _id
        - isNpnRequired
        - legalName
        - category
        - npn
        - ein
    ComplianceDataSubscriptionResponse:
      type: object
      properties:
        dataOwnerId:
          type: string
          description: Data owner ID
        dataOwnerModel:
          type: string
          description: Data owner model type
        entityModel:
          type: string
          description: Entity model type
        npn:
          type: string
          description: National Producer Number
          nullable: true
        entityInfo:
          description: NIPR entity info details
          allOf:
            - $ref: '#/components/schemas/NiprEntityInfoResponse'
        lastSynchronizationDate:
          format: date-time
          type: string
          description: Last synchronization date
        pdbAlertsSubscriptionStatus:
          type: string
          description: PDB Alerts subscription status
        pdbAlertsPausedAt:
          format: date-time
          type: string
          description: Date when PDB Alerts was paused
      required:
        - dataOwnerId
        - dataOwnerModel
        - entityModel
        - entityInfo
    AssociationAddressResponse:
      type: object
      properties:
        line1:
          type: string
          description: Street address line 1
          example: 1200 Market St
        line2:
          type: string
          description: Street address line 2
          example: Suite 400
        city:
          type: string
          description: City
          example: Philadelphia
        zip:
          type: string
          description: ZIP code
          example: '19107'
        state:
          type: string
          description: Two-letter state code
          enum:
            - AL
            - AK
            - AZ
            - AR
            - CA
            - CO
            - CT
            - DE
            - FL
            - GA
            - HI
            - ID
            - IL
            - IN
            - IA
            - KS
            - KY
            - LA
            - ME
            - MD
            - MA
            - MI
            - MN
            - MS
            - MO
            - MT
            - NE
            - NV
            - NH
            - NJ
            - NM
            - NY
            - NC
            - ND
            - OH
            - OK
            - OR
            - PA
            - RI
            - SC
            - SD
            - TN
            - TX
            - UT
            - VT
            - VA
            - WA
            - WV
            - WI
            - WY
          example: PA
        country:
          type: string
          description: Country
          example: USA
      required:
        - country
    NiprEntityInfoResponse:
      type: object
      properties:
        status:
          type: string
          description: Status of the NIPR data subscription
        jobId:
          type: string
          description: Job ID for the NIPR entity info request
        message:
          type: string
          description: Message associated with the status
        rawEntityInfoId:
          type: string
          description: Raw entity info document ID
        awaitingBusinessCopyDate:
          type: string
          description: >-
            Set only while a sync is held for NIPR's nightly update (a first
            sync, or a sync after monitoring was paused): the date of the NIPR
            update it is waiting for (YYYY-MM-DD). The sync runs once that
            update is available, usually early on that date, Central time.
          example: '2026-11-17'
      required:
        - status
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    restricted-access-token:
      type: apiKey
      in: header
      name: x-restricted-access-token
      description: >-
        Alternative authentication: Restricted access token (if not using Bearer
        token)

````

## Related topics

- [Changelog](https://docs.turrisfi.com/changelog.md)
- [Add a Producer](https://docs.turrisfi.com/api-reference/v2/downstream/producers/add-producer.md)
- [Add a Licensed Entity](https://docs.turrisfi.com/api-reference/v2/downstream/entities/add-entity.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.