Skip to main content
The core entities and their relationships with each other are described below. Please also inspect the documentation for each entity family for more detail.

​
1. Downstream Entity Associations

Endpoint: /downstream-entity-associations Purpose: Manage the relationship between upstream entities (insurance carriers/MGAs) and downstream entities (agencies, brokerages).

​
Many-to-Many Relationship

Downstream Entity Associations (internally called UpstreamDownstreamAssociation) represent a many-to-many relationship between Upstream Entities and Downstream Entities:
  • One Agency → Many Carriers/MGAs: A single agency can be associated with multiple upstream entities (carriers, MGAs, wholesalers)
  • One Carrier/MGA → Many Agencies: A single upstream entity can have relationships with hundreds or thousands of agencies
Each association is a unique pairing with its own:
  • downstreamEntityAssociationId — The unique identifier used in API endpoints
  • Compliance documents (E&O, Cyber, W9) scoped to that specific relationship
  • NIPR data subscription for license/appointment data owned by the upstream entity
  • Producer codes, business rules, and onboarding settings specific to the relationship
  • Soft-delete capability (isDeleted: true) without affecting the underlying entities
When querying the API, you work with downstreamEntityAssociationId — not the downstream entity’s ID directly. This ensures data isolation between upstream entities even when they share associations with the same agency.

​
Core Functionality

  • Add downstream entities directly without invitation
  • Invite downstream entities via email
  • Sync compliance data from NIPR
  • Get policy compliance status for E&O and Cyber policies

​
Key Features

  • Hierarchical Structure: Supports parent-child relationships for branch organizations
  • Producer Codes: Unique identifiers for each association bounded by the tenancy of an Upstream Entity
  • Business Rules: Inherited from upstream entity (policy grace periods, coverage minimums, auto-authorization)
  • Onboarding Settings: Controls which steps are required during downstream entity onboarding
  • NIPR Integration: Automatic data subscription for NPN-based entities

​
2. Agents

Endpoint: /agents Purpose: Manage individual insurance agents. Agents can be associated with Downstream Entities and/or directly with Upstream Entities via the Downstream Entity Association Table.

​
Core Functionality

  • Add agents by NPN
  • Get agent details with compliance data
  • List agents for a downstream entity association
  • Sync agent data from NIPR

​
Key Features

  • NIPR Sync: Agents are synced from NIPR database using NPN
  • License Tracking: State licenses with lines of authority
  • Authority Management: Requested vs approved states per upstream entity product
  • Assignment Status: Track agent’s active status within downstream entity
  • Multi-Association: Same agent can be associated with multiple Downstream Entities and/or Downstream Entity Associations

​
3. Licenses

Endpoint: /licenses Purpose: Access license compliance data for agents and downstream entities.

​
Sub-Resources

  • Agent Licenses
  • Downstream Entity Licenses

​
Key Features

  • State-Level Tracking: Individual licenses per state
  • Renewal Dates: Track expiration and renewal cycles
  • Lines of Authority: Specific insurance types the license covers
  • Residency Status: Resident vs non-resident licenses
  • NIPR Source: All license data synced from NIPR

​
4. License Compliance

Endpoint: /license-compliance Purpose: Evaluate compliance status of agents and downstream entities against upstream entity requirements.

​
Sub-Resources

  • Agents License Compliance
  • Downstream Entities License Compliance

​
Core Functionality

  • Compliance Evaluation: Check if licenses meet upstream entity requirements
  • State Coverage: Verify required states are covered
  • Expiration Monitoring: Track upcoming renewals
  • Authority Matching: Ensure lines of authority align with products

​
Key Features

  • Product-Based Requirements: Different products may require different states/LOAs
  • Grace Periods: Configurable grace periods for expired licenses
  • Compliance Status: Compliant, non-compliant, expiring soon
  • Aggregation Pipelines: Complex queries to evaluate compliance across multiple dimensions

​
5. File Documents

Endpoint: /file-documents Purpose: Upload and manage PDF documents (policies, contracts, W9s, etc.) for downstream entities.

​
Core Functionality

  • Upload PDF documents (E&O, Cyber, Producer Agreements, W9, etc.)
  • Versioning: Automatically create new versions when re-uploading same category
  • Document Categories: E&O, Cyber, Producer Agreement, W9, Crime & Fidelity, Other Contract, Payment Details, License PDF

​
Key Features

  • S3 Storage: Documents stored in AWS S3 with versioning
  • Multi-Owner: Documents can be owned by both upstream and downstream entities
  • Access Control: Read/Write permissions per owner
  • Metadata Extraction: Automatic data extraction for E&O and Cyber policies
  • Association Tracking: Links documents to specific upstream-downstream relationships

​
6. Compliance Data Subscriptions

Endpoint: /compliance-data-subscriptions Purpose: Monitor the status of NIPR data synchronization jobs.

​
Core Functionality

  • Get sync status for a specific NIPR data subscription
  • Track job progress (not started, in progress, success, failed)

​
Key Features

  • Job Tracking: Monitor NIPR API calls and data sync status
  • Entity Info: Basic entity information from NIPR
  • License Sync: Automatically creates/updates license records
  • Appointment Sync: Tracks carrier appointments
  • Regulatory Actions: Monitors disciplinary actions
  • PDB Alerts: Optional subscription to Producer Database alerts

​
Data Flow Examples

​
Adding a Downstream Entity

1. POST /downstream-entity-associations/add
   ↓
2. Creates downstream-entity (if new NPN)
   ↓
3. Creates downstream-entity-association
   ↓
4. Creates nipr-data-subscription
   ↓
5. Enqueues NIPR sync job (provided auto-sync feature is enabled)
   ↓
6. Syncs entity info, licenses, appointments
   ↓
7. Creates licenses, appointments, and regulatory actions records

​
Adding an Agent

1. POST /agents
   ↓
2. Creates/finds agent by NPN
   ↓
3. Adds agent to downstream-entity-association.agents[]
   ↓
4. Creates nipr-data-subscription for agent
   ↓
5. Enqueues NIPR sync job (provided auto-sync feature is enabled)
   ↓
6. Creates license, appointments, and regulatory actions records

​
Uploading a Document

1. POST /file-documents
   ↓
2. Validates association exists
   ↓
3. Uploads PDF to S3
   ↓
4. Creates/updates file-document
   ↓
5. Creates file-document-association
   ↓
6. Enqueues data extraction job (for E&O/Cyber)
   ↓
7. Extracts metadata into policy collection

​
Checking License Compliance

1. GET /license-compliance/agents/:agentId
   ↓
2. Fetches agent-licenses
   ↓
3. Fetches upstream-entity-products requirements
   ↓
4. Evaluates compliance per state/product
   ↓
5. Returns compliance status with gaps

​
Key Design Patterns

PatternDescription
Association-CentricThe downstream-entity-association is the central hub connecting all resources
NIPR IntegrationMost compliance data originates from NIPR, stored and referenced in nipr-data-subscriptions
Hierarchical OrganizationsSupport for parent-child relationships in both entities and associations
Document VersioningFile documents support multiple versions with S3 versioning
Multi-TenancyAll resources are scoped to upstreamEntityId for data isolation
Async ProcessingNIPR syncs and document extraction happen asynchronously via job queues
Embedded vs ReferencedContacts and authority are embedded in associations; licenses and documents are separate collections
Soft DeletesMost resources use isDeleted flag rather than hard deletes