Skip to main content
POST
Add an NPN
Adds an NPN to an agency you added with Add 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.

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 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. Send an Idempotency-Key header to retry safely: a repeated request with the same key returns the original response instead of 409.
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.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

idempotency-key
string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

x-idempotency-key
string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Path Parameters

downstreamEntityAssociationId
string
required

Downstream entity association ID

Example:

"507f1f77bcf86cd799439011"

Body

application/json
npn
string
required

The agency's National Producer Number (NPN), 1 to 10 digits. Leading zeros are dropped when it is stored.

Example:

"12345678"

Response

The association, now carrying the NPN, the legal name from NIPR and the compliance data subscription

data
object
required
requestId
string
required

Unique request identifier

Example:

"dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8"

timestamp
string
required

Response timestamp

Example:

"2025-11-12T20:49:03.293Z"