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

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

{
  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

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

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

{
  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"
  }]
}

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.

Deep Dive

Field-by-field walkthrough of the Vehicle object.

Vehicle Fields

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.

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:

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

DirectLoan - Financing & Refinancing

For title work involving loans or refinances.

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

Sale - Vehicle Transfers

For dealer sales, private party sales, or gifts.

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

Repo - Repossession Processing

For vehicle repossession workflows.

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

Salvage - Total Loss Processing

For insurance total loss or salvage title work.

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

Title entry projections

Beyond account_data, complete title entries may expose derived fields for review automation:

Account Facts

The account_facts object — four crystallized judgements (borrower_on_title, signature sufficiency, problematic brands, active liens) with summaries and references. Preview / not GA.

Get Started

Guides

Resources

Core Ontology

The Cardinal Gray Data Model

The Vehicle Object

Overview

1. Identity & Classification

2. Ownership Information

3. Registration Information

Deep Dive

Vehicle Fields

VehicleTitle Fields

Transaction Types

Title entry projections

Account Facts

Next Steps

Data Enrichment

API Reference

​The Cardinal Gray Data Model

​The Vehicle Object

​Overview

​1. Identity & Classification

​2. Ownership Information

​3. Registration Information

​Deep Dive

​Vehicle Fields

​VehicleTitle Fields

​Transaction Types

​Title entry projections

Account Facts

​Next Steps

Data Enrichment

API Reference

The Cardinal Gray Data Model

The Vehicle Object

Overview

1. Identity & Classification

2. Ownership Information

3. Registration Information

Deep Dive

Vehicle Fields

VehicleTitle Fields

Transaction Types

Title entry projections

Next Steps