> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylon.mortgage/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity relationships

> Understanding how entities relate to each other is essential for working with the Pylon API. This page provides a high-level overview of the data model and explains the relationships between core entities.

## Entity relationship diagram

The following diagram shows the primary entities and their relationships:

```mermaid theme={null}
erDiagram
    Deal ||--o{ Borrower : contains
    Deal ||--o{ Loan : contains
    Deal ||--o{ Party : contains

    Borrower ||--o{ Income : has
    Borrower ||--o{ Asset : owns
    Borrower ||--o{ Liability : owes
    Borrower ||--o{ OwnedProperty : owns
    Borrower ||--|| BorrowerCredit : has

    Loan ||--o| SubjectProperty : has
    Loan ||--o{ Document : contains
    Loan ||--o| LoanOfficer : "assigned to"
    Loan ||--o{ Appraisal : has

    OwnedProperty ||--o{ Liability : "secured by"
    SubjectProperty ||--o{ Liability : "secured by"
```

## Relationship patterns

### One-to-many relationships

Most relationships in the API are one-to-many:

* A Deal has many Borrowers
* A Deal has many Loans
* A Borrower has many Incomes
* A Borrower has many Assets
* A Borrower has many Liabilities
* A Borrower has many Owned Properties
* A Loan has many Documents

### Many-to-many relationships

Some entities have many-to-many relationships, implemented through shared references:

* **Borrowers and Assets** - Multiple borrowers can be account holders on a single asset (e.g., a joint checking account). The `borrowerIds` field on an asset lists all borrower owners.
* **Owned Properties and Borrowers** - Multiple borrowers can own the same property, and a borrower can own multiple properties.

### Optional relationships

Some relationships are optional depending on the loan scenario:

* A `Loan` may or may not have a `SubjectProperty` (early in the process, only a `SubjectPropertyIntent` may exist).
* A `Loan` may or may not have an `assignedLoanOfficer`.
* An `ownedProperty` may or may not have associated `liabilities` (if owned free and clear).

## Navigating the API

When working with the API, you'll typically start at the Deal level and traverse down to the entities you need.

For the complete field reference and available operations, see the [GraphQL API Reference](https://pylon.mortgage/documentation/graphql/index.html).