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

# Core Ontology

> Understanding Cardinal Gray

# The Cardinal Gray Data Model

Cardinal Gray's API is built around an opinionated, transaction-agnostic data model that separates **what we're dealing with** (the vehicle) from **where we're taking it** (the transaction).

* **Vehicle** (descriptive): The source of truth for VIN, make, model, title information, and registration data
* **Transaction** (prescriptive): How you're working with this vehicle: loan, sale, repo, or salvage

```typescript theme={null}
interface AccountData {
  vehicle: Vehicle;    // Required: Always present
  loan?: DirectLoan;   // Optional loan origination data
  repo?: Repo;         // Optional when collateral enters repo status
  sale?: Sale;         // Optional dealer or private ownership transfer
  salvage?: Salvage;   // Optional for salvage/total loss processing
}
```

***

## The Vehicle Object

### Overview

The `Vehicle` object is the **descriptive core** of every title entry. It contains:

#### 1. Identity & Classification

```typescript theme={null}
{
  vin: "1HGCM82633A123456",        // duh
  year: "2003",                    // Model year
  make: "Honda",                   // Manufacturer
  model: "Accord",                 // Model name
  // enum and state literals of vehicle type, class
  // body, style... and more!
}
```

#### 2. Ownership Information

```typescript theme={null}
vehicle: {
  // vin, make, year, model, motorcycle engine no., etc. 
  title: {
    number: "T1234567",                   // Title number
    issuing_state: "CA",                  // State that issued the title
    issuing_county: "Los Angeles",        // County of issuance (if relevant)
    issuance_date: "01/15/2023",          // When title was issued
    status: "active",                     // Enumeration of title status
    status_raw_text: "ACTIVE - NO HOLDS", // Original DMV portal text

    // Odometer information
    odometer_reading: "45123",
    odometer_code_translation: "ACTUAL",  // ACTUAL | NOT_ACTUAL | EXEMPT

    // Ownership details
    owner_names_one_line: "JOHN AND JANE DOE",
    owners: [{ name: "John Doe", ownership_type: "titled_owner" ... }],
    conjunction: "AND",                   // In the case of multiple owners

    // Lien information
    has_liens: true,
    active_liens: [{
      lien_date: "01/20/2023",
      lienholder: { name: "First Bank", elt_id: "FB123", ... }
    }],

    // Brand history
    brands: [{
      brand: "NONE",                       // Enumerated brand "translation"
      nmvtis_code: "0",
      state_code: "00"
    }]
  }
}
```

#### 3. Registration Information

<Note>
  Registered vs titled owners are distinguished within the `title.owners` via the `ownership_type` enum, which is ordered based
  on ownership priority!
</Note>

```typescript theme={null}
{
  license_plate: "ABC1234",
  license_plate_type: "PASSENGER",
  registration_status: "ACTIVE",                // ACTIVE | EXPIRED | SUSPENDED/REVOKED
  registration_expiration_date: "12/31/2024",
  registration_issuance_date: "12/31/2023",

  // Registration/title holds
  has_reg_title_holds: false,
  reg_title_holds: [{
    hold_type: "INSURANCE",                    // INSURANCE | LIEN | FEE | SUSPENSION | etc.
    hold_description: "Proof of insurance required",
    issue_date: "06/15/2023",
    source: "DMV"
  }]
}
```

<Check>
  **Data Enrichment:** When you POST a title with `sync_nmvtis`, `sync_public`, or `sync_private` flags, Cardinal Gray automatically populates these fields with real-time DMV data. You only need to provide the VIN and we handle the rest.
</Check>

### Deep Dive

Field-by-field walkthrough of the `Vehicle` object.

#### Vehicle Fields

<Warning>
  **Holds Block Transactions:** If `has_reg_title_holds` is `true`, you may not be able to complete certain DMV transactions until the holds are cleared. The `reg_title_holds` array provides details on what needs to be resolved.
</Warning>

The following fields are available on the `Vehicle` object from DMV data enrichment:

| Field                          | Description                       |
| ------------------------------ | --------------------------------- |
| `vin`                          | Vehicle Identification Number     |
| `year`                         | Vehicle model year                |
| `make`                         | Vehicle manufacturer              |
| `model`                        | Vehicle model name                |
| `body`                         | Body style                        |
| `type`                         | Vehicle type classification       |
| `color`                        | Primary color                     |
| `color_secondary`              | Secondary color                   |
| `fuel_type`                    | Fuel type                         |
| `use`                          | Vehicle use classification        |
| `weight`                       | Vehicle weight                    |
| `weight_rating`                | Weight rating classification      |
| `weight_gross`                 | Gross vehicle weight              |
| `weight_unladen`               | Unladen weight                    |
| `width`                        | Vehicle width                     |
| `length`                       | Vehicle length                    |
| `bhpcc`                        | BHP/CC rating                     |
| `number_of_axles`              | Number of axles                   |
| `number_of_cylinders`          | Number of cylinders               |
| `license_plate`                | License plate number              |
| `license_plate_type`           | Plate type                        |
| `motorcycle_engine_number`     | Motorcycle engine number          |
| `registration_status`          | Current registration status       |
| `registration_expiration_date` | Registration expiration date      |
| `registration_issuance_date`   | Registration issuance date        |
| `class`                        | Vehicle class                     |
| `has_reg_title_holds`          | Whether holds exist               |
| `reg_title_holds`              | Array of registration/title holds |
| `prev_date_of_sale`            | Previous sale date                |
| `prev_sale_price`              | Previous sale price               |
| `fee_history`                  | Historical fee data               |
| `insurance`                    | Insurance information             |

#### VehicleTitle Fields

The following fields are available on the nested `VehicleTitle` object:

| Field                       | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| `number`                    | Title number                                          |
| `issuing_state`             | State that issued the title                           |
| `issuing_county`            | County where title was issued                         |
| `issuance_date`             | Title issuance date                                   |
| `brand`                     | Title brand (deprecated)                              |
| `brand_code`                | Brand code (deprecated)                               |
| `brands`                    | Array of brand details with NMVTIS codes              |
| `odometer_reading`          | Odometer reading at title issuance                    |
| `odometer_reading_unit`     | MI or KM                                              |
| `odometer_code`             | Odometer status code                                  |
| `odometer_code_translation` | Human-readable odometer status                        |
| `has_liens`                 | Whether liens exist                                   |
| `active_liens`              | Array of active liens                                 |
| `is_electronic`             | Electronic title flag                                 |
| `is_and`                    | AND ownership conjunction                             |
| `is_or`                     | OR ownership conjunction                              |
| `is_tod`                    | Transfer on Death flag                                |
| `is_jtwros`                 | Joint Tenants With Right of Survivorship              |
| `conjunction`               | Ownership conjunction type                            |
| `is_leased`                 | Leased vehicle flag                                   |
| `previous_title`            | Previous title information                            |
| `owner_names_one_line`      | Concatenated owner names                              |
| `number_of_owners`          | Number of owners                                      |
| `owners`                    | Array of owner Person objects                         |
| `status`                    | Title status (active, inactive, pending, etc.)        |
| `status_raw_text`           | Raw status text from source                           |
| `prev_action`               | Previous action (original, transfer, duplicate, etc.) |
| `prev_action_raw_text`      | Raw previous action text                              |

***

## Transaction Types

Each transaction type is purpose-built for specific workflows, modeling the information you collect within a loan origination system or deal flow:

<Note>
  Reach out to support for information on auto-populating transaction keys for your specific workflow needs
</Note>

<AccordionGroup>
  <Accordion title="DirectLoan - Financing & Refinancing" icon="hand-holding-dollar">
    For title work involving loans or refinances.

    ```typescript theme={null}
    {
      loan: {
        new_lienholder: { name, elt_id, addr },
        borrower: [{ name, dob, addr }],
        loan_amount: 25000,
        // For refinances:
        prior_lien: { lienholder, lien_date, lien_amount }
      }
    }
    ```

    **Use cases:** Frontend lien perfection, refinances, lien additions.
  </Accordion>

  <Accordion title="Sale - Vehicle Transfers" icon="handshake">
    For dealer sales, private party sales, or gifts.

    ```typescript theme={null}
    {
      sale: {
        type: "NEW" | "USED" | "GIFT",
        sale_price: 18500,
        buyer: { name, dob, addr, insurance },
        seller: { name, addr, dealer_id? },
        financed?: { lienholder, lien_date }
      }
    }
    ```

    **Use cases:** Dealer sales, private party transfers, gift transfers.
  </Accordion>

  <Accordion title="Repo - Repossession Processing" icon="truck-tow">
    For vehicle repossession workflows.

    ```typescript theme={null}
    {
      repo: {
        reposession_date: "03/15/2024",
        reposession_address: { street1, city, state, zip },
        reposession_agency: "Recovery Services Inc",
        reposession_agency_address: { ... }
      }
    }
    ```

    **Use cases:** Repo title acquisition, affidavit generation, post-repo sales.
  </Accordion>

  <Accordion title="Salvage - Total Loss Processing" icon="car-burst">
    For insurance total loss or salvage title work.

    ```typescript theme={null}
    {
      salvage: {
        type: "THEFT" | "DAMAGE",
        date_of_loss: "04/10/2024",
        total_loss_value: 15000,
        insurance_company: "Progressive"
      }
    }
    ```

    **Use cases:** Salvage title applications, total loss settlements, rebuilt titles.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Enrichment" icon="database" href="/guides/data-enrichment">
    Learn how NMVTIS, state DMV, and portal data flows work
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/v1/post_title">
    Jump into the endpoint documentation
  </Card>
</CardGroup>