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

# Entity & Resource Definitions

> Core entities and their relationships in the Turris API

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

```mermaid theme={null}
erDiagram
    UPSTREAM_ENTITY ||--o{ DOWNSTREAM_ASSOCIATION : "has many"
    DOWNSTREAM_ENTITY ||--o{ DOWNSTREAM_ASSOCIATION : "has many"
    
    UPSTREAM_ENTITY {
        string id PK
        string name
        string type "Carrier, MGA, Wholesaler"
    }
    
    DOWNSTREAM_ASSOCIATION {
        string id PK "downstreamEntityAssociationId"
        string upstreamEntityId FK
        string downstreamEntityId FK
        string producerCode
        boolean isDeleted
    }
    
    DOWNSTREAM_ENTITY {
        string id PK
        string legalName
        string npn
        string type "Agency, Brokerage"
    }
```

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

<Note>
  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.
</Note>

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

| Pattern                        | Description                                                                                          |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| **Association-Centric**        | The downstream-entity-association is the central hub connecting all resources                        |
| **NIPR Integration**           | Most compliance data originates from NIPR, stored and referenced in nipr-data-subscriptions          |
| **Hierarchical Organizations** | Support for parent-child relationships in both entities and associations                             |
| **Document Versioning**        | File documents support multiple versions with S3 versioning                                          |
| **Multi-Tenancy**              | All resources are scoped to upstreamEntityId for data isolation                                      |
| **Async Processing**           | NIPR syncs and document extraction happen asynchronously via job queues                              |
| **Embedded vs Referenced**     | Contacts and authority are embedded in associations; licenses and documents are separate collections |
| **Soft Deletes**               | Most resources use isDeleted flag rather than hard deletes                                           |