This page describes the carrier surface: the entities behind
/v2/upstream/* and their v1 equivalents. If you also read the agency endpoints, the two surfaces name the same records with different words. The same records, two vocabularies maps one onto the other.1. Downstream Entity Associations
Endpoint:/v2/upstream/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 calledUpstreamDownstreamAssociation) 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
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:/v2/upstream/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
Endpoints:/v2/upstream/agents/{agentId}/licenses/v2/upstream/agents/licenses/v2/upstream/downstream-entity-associations/{downstreamEntityAssociationId}/licenses/v2/upstream/downstream-entity-associations/licenses
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
Endpoints:/v2/upstream/agents/{agentId}/license-compliance-statuses/v2/upstream/downstream-entity-associations/{downstreamEntityAssociationId}/license-compliance-statuses
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:/v2/upstream/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:/v2/upstream/compliance-data-subscriptions/{niprDataSubscriptionId}
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