> ## 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. # Create Title Entry > Create a new title entry with vehicle information or document uploads ## OpenAPI ````yaml POST /title openapi: 3.0.1 info: title: Cardinal Gray OpenAPI description: OpenAPI for automating vehicle title work license: name: MIT version: 1.0.0 servers: - url: https://dev.cardinalgray.com description: Development - url: https://api.cardinalgray.com description: Production security: - bearerAuth: [] paths: /title: post: summary: Create a new title entry description: >- Creates a new title entry with either structured vehicle/loan/sale data or document uploads for processing. If a VIN already exists for your organization, the request will update the existing entry instead of creating a new one. requestBody: description: >- Title entry data - either structured AccountData or document URLs for processing content: application/json: schema: oneOf: - $ref: '#/components/schemas/PostTitleData' title: Multimodal Request description: >- Recommended format: combine document uploads with partial structured data for best results - type: object title: Document Upload description: >- Legacy format: Upload documents only for automated processing required: - attachments properties: attachments: type: array description: >- Array of URLs pointing to documents (PDF, JPG, PNG) to be processed via OCR and data extraction items: type: string format: uri example: https://example.com/documents/vehicle-title.pdf minItems: 1 maxItems: 10 example: attachments: - https://example.com/title.pdf - https://example.com/drivers-license.jpg - $ref: '#/components/schemas/AccountData' title: Structured Data description: >- Legacy format: Complete vehicle, loan, and/or sale information as structured data required: true responses: '200': description: Existing entry updated (when VIN already exists) content: application/json: schema: type: object properties: entryId: type: string description: Unique identifier for the updated title entry format: uuid example: 550e8400-e29b-41d4-a716-446655440000 job_status: $ref: '#/components/schemas/JobStatus' description: Will be 'pending' for updated entries example: pending required: - entryId - job_status '201': description: Title entry created successfully content: application/json: schema: type: object properties: entryId: type: string description: Unique identifier for the created title entry format: uuid example: 550e8400-e29b-41d4-a716-446655440000 job_status: $ref: '#/components/schemas/JobStatus' description: Will be 'pending' for new entries example: pending required: - entryId - job_status '400': description: >- Invalid request - missing required fields, unsupported file types, or malformed data content: application/json: schema: $ref: '#/components/schemas/Response' '403': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' components: schemas: PostTitleData: type: object description: >- Combined structured and unstructured data for title entry creation. This format allows you to provide both document uploads and partial structured data for optimal processing results. properties: attachments: type: array items: type: string format: uri description: >- Array of document URLs to be processed via OCR and data extraction. Supported formats: PDF, JPG, PNG account_data: allOf: - $ref: '#/components/schemas/AccountData' description: >- Additional structured data, such as loan applicant information. Data will be intelligently merged with OCR-extracted data. groupId: type: string description: >- Optional user group ID for organizational access control and workflow routing sync_nmvtis: type: boolean description: Whether to sync NMVTIS data sync_public: type: boolean description: Whether to sync public DMV data sync_private: type: boolean description: Whether to sync private DMV data dppa_exemption: type: string description: >- Driver's Privacy Protection Act exemption code; required if sync_nmvtis or sync_private is set to true; default: legitimate_business_need example: attachments: - https://example.com/vehicle-title.pdf - https://example.com/drivers-license.jpg account_data: vehicle: vin: 1HGCM82633A123456 loan: borrower: - name: John Doe contact_email: john.doe@example.com contact_phone: 123-456-7890 groupId: branch-5321 AccountData: type: object properties: vehicle: $ref: '#/components/schemas/Vehicle' loan: $ref: '#/components/schemas/DirectLoan' sale: $ref: '#/components/schemas/Sale' repo: $ref: '#/components/schemas/Repo' salvage: $ref: '#/components/schemas/Salvage' required: - vehicle JobStatus: type: string enum: - pending - input_parsing - enriching - generating_forms - complete - error description: >- Processing status of the title entry workflow. Statuses: 'pending' - Initial state when job is created; 'input_parsing' - Processing uploaded documents and extracting data; 'enriching' - Enriching data with NMVTIS/DMV data or calculating fees; 'generating_forms' - Generating DMV forms for submission; 'complete' - Successfully completed all processing; 'error' - Error state for any processing failures Response: type: object properties: error: type: string description: Error message statusCode: type: number description: HTTP status code Vehicle: type: object properties: vin: type: string description: Vehicle Identification Number (17 characters) pattern: ^[A-HJ-NPR-Z0-9]{17}$ example: 1HGCM82633A123456 year: oneOf: - type: string - type: number description: Vehicle model year example: 2023 make: type: string description: Vehicle manufacturer (e.g., Honda, Ford, Toyota) example: Honda model: type: string description: Vehicle model name example: Accord body: type: string type: $ref: '#/components/schemas/VehicleTypeEnum' color: type: string color_secondary: type: string fuel_type: type: string use: type: string description: Vehicle use classification weight: oneOf: - type: string - type: number weight_rating: type: string description: Weight rating classification weight_gross: oneOf: - type: string - type: number weight_unladen: oneOf: - type: string - type: number width: type: string length: type: string bhpcc: type: string number_of_axles: type: string number_of_cylinders: type: string license_plate: type: string license_plate_type: type: string motorcycle_engine_number: type: string registration_status: type: string enum: - ACTIVE - EXPIRED - SUSPENDED/REVOKED description: Current status of the vehicle's registration registration_expiration_date: type: string registration_issuance_date: type: string description: Date when the current registration was issued class: type: string has_reg_title_holds: type: boolean description: Whether the vehicle has outstanding registration or title holds reg_title_holds: type: array items: type: object description: Represents a hold or stop on a vehicle's registration or title properties: hold_type: type: string enum: - INSURANCE - LIEN - FEE - SUSPENSION - STOP - OTHER description: Type of hold placed on the registration or title hold_code: type: string description: State-specific code for this hold type hold_description: type: string description: Human-readable description of the hold issue_date: type: string description: Date the hold was issued clear_date: type: string description: Date the hold was cleared (if applicable) source: type: string description: Source of the hold (e.g., 'DMV', 'COURT', 'LIENHOLDER') required: - hold_type description: Outstanding registration or title holds on the vehicle prev_date_of_sale: type: string prev_sale_price: type: string description: Price of the previous sale (if known) fee_history: type: array items: $ref: '#/components/schemas/TransactionFee' insurance: $ref: '#/components/schemas/Insurance' title: $ref: '#/components/schemas/VehicleTitle' required: - vin DirectLoan: type: object properties: new_lienholder: $ref: '#/components/schemas/Lienholder' borrower: type: array items: $ref: '#/components/schemas/Person' loan_id: type: string security_agreement_sign_date: type: string loan_amount: type: number payoff_amount: type: number per_diem: type: number prior_lien: $ref: '#/components/schemas/Lien' add_owner: type: array items: $ref: '#/components/schemas/Person' drop_owner: type: array items: $ref: '#/components/schemas/Person' release_title_to_address: $ref: '#/components/schemas/Address' required: - new_lienholder - borrower Sale: type: object properties: type: $ref: '#/components/schemas/SaleTypeEnum' description: >- Type of vehicle sale - NEW for new vehicles from dealer, USED for pre-owned vehicles, GIFT for transfers without payment sale_type: $ref: '#/components/schemas/SaleTypeEnum' description: Alternative field name for sale type (synonym of 'type') sale_price: type: number description: Total sale price of the vehicle in US Dollars date_of_sale: type: string state: type: string description: State in which the sold vehicle is being titled and registered seller: oneOf: - $ref: '#/components/schemas/Person' - $ref: '#/components/schemas/Dealer' buyer: oneOf: - type: array items: $ref: '#/components/schemas/Person' description: Array of buyers (persons) - $ref: '#/components/schemas/Dealer' description: Dealer as buyer description: Vehicle buyer - can be an array of persons or a dealer financed: $ref: '#/components/schemas/Lien' delivery_date: type: string additional_dues: $ref: '#/components/schemas/AdditionalDues' trade_in: $ref: '#/components/schemas/Vehicle' required: - type - sale_price - date_of_sale - state - additional_dues Repo: type: object properties: reposession_date: type: string description: Date of vehicle repossession reposession_address: $ref: '#/components/schemas/Address' description: Address where the vehicle was repossessed reposession_agency: type: string description: Name of the repossession agency reposession_agency_address: $ref: '#/components/schemas/Address' description: Address of the repossession agency required: - reposession_date - reposession_address - reposession_agency - reposession_agency_address Salvage: type: object properties: type: type: string enum: - THEFT - DAMAGE insurance: $ref: '#/components/schemas/Insurance' claim_number: type: string total_loss_date: type: string payoff_date: type: string VehicleTypeEnum: type: string enum: - AUTO - OHV - ORV - ATV - MOTORCYCLE - LOW_SPEED - TRAILER - BOAT description: >- Type of vehicle. AUTO for passenger vehicles, OHV for off-highway vehicles, ORV for off-road vehicles, ATV for all-terrain vehicles, MOTORCYCLE, LOW_SPEED for low-speed vehicles, TRAILER, BOAT TransactionFee: type: object properties: feeType: type: string description: Type of fee (e.g., 'StateTax', 'TitleFee', 'RegFee') name: type: string description: Human-readable name of the fee value: type: number description: Fee amount in dollars Insurance: type: object properties: provider_name: type: string description: Insurance company name (e.g., 'GEICO', 'State Farm') provider_naic: type: string description: National Association of Insurance Commissioners code policy_number: type: string description: Insurance policy number description: Vehicle insurance information VehicleTitle: type: object properties: number: type: string description: Vehicle title number issuing_state: type: string description: State that issued the title (e.g., 'FL', 'TX') issuing_county: type: string description: County where the title was issued issuance_date: type: string format: date description: Date the title was issued (YYYY-MM-DD) brand: $ref: '#/components/schemas/VehicleBrandEnum' description: >- Title brand indicating the vehicle's condition or history (DEPRECATED - use brands array instead) brand_code: type: string description: >- Numeric or alphanumeric code associated with the title brand (DEPRECATED) brands: type: array description: Array of vehicle brand details with NMVTIS and state codes items: type: object properties: brand: $ref: '#/components/schemas/VehicleBrandEnum' nmvtis_code: type: string description: NMVTIS code for this brand state_code: type: string description: State-specific code for this brand required: - brand odometer_reading: type: string description: >- Odometer reading at the time of title issuance, usually in miles or kilometers odometer_reading_unit: type: string enum: - MI - KM description: >- Unit of measurement for odometer reading (MI for miles, KM for kilometers) odometer_code: type: string description: Code indicating the status or accuracy of the odometer reading odometer_code_translation: $ref: '#/components/schemas/OdometerStatusEnum' has_liens: type: boolean active_liens: type: array items: $ref: '#/components/schemas/Lien' is_electronic: type: boolean is_and: type: boolean is_or: type: boolean is_tod: type: boolean description: >- Whether the title has a TOD (Transfer on Death) conjunction in the ownership line is_jtwros: type: boolean description: >- Whether ownership is Joint Tenants With Right of Survivorship (JTWROS) conjunction: type: string enum: - AND - OR - TOD - AND/OR - JTWROS - UNKNOWN description: >- Ownership conjunction type. Replaces individual boolean flags (is_and, is_or, is_tod, is_jtwros) is_leased: type: boolean description: Whether the vehicle is leased rather than owned previous_title: $ref: '#/components/schemas/VehicleTitle' owner_names_one_line: type: string number_of_owners: type: number owners: type: array items: $ref: '#/components/schemas/Person' status: type: string enum: - active - inactive_transferred_out_of_state - inactive_cancelled - inactive_sold - inactive_revoked - inactive_suspended - pending - unknown description: >- Opinionated but stable title status indicating the current state of the title status_raw_text: type: string description: >- Raw text from the portal/source system for the title status (preserved for reference) prev_action: type: string enum: - original - renewal - transfer - duplicate - replacement - correction - elt2paper - update - nonresident - unknown description: >- Previous action taken on this title (e.g., was it an original title, a transfer, a duplicate request, etc.) prev_action_raw_text: type: string description: >- Raw text from the portal/source system for the previous action (preserved for reference) Lienholder: allOf: - $ref: '#/components/schemas/Entity' - type: object properties: type: type: string enum: - LIENHOLDER address_vault: $ref: '#/components/schemas/Address' elt_id: type: string feid: type: string signatory: $ref: '#/components/schemas/Person' Person: allOf: - $ref: '#/components/schemas/Entity' - type: object properties: type: type: string enum: - PERSON - BUSINESS dob: type: string contact_phone: type: string contact_email: type: string dlid: $ref: '#/components/schemas/DriversLicense' ssn: type: string addr_mailing: $ref: '#/components/schemas/Address' insurance: $ref: '#/components/schemas/Insurance' ownership_type: type: string description: >- Type of ownership (e.g., SOLE, JOINT, LEASED, TRUST, registered_owner, titled_owner) is_nonobligor: type: boolean description: Whether this person is a non-obligor on the loan required: - dob Lien: type: object properties: lien_date: type: string description: Date the lien was filed lien_amount: oneOf: - type: string - type: number description: Amount of the lien lien_id: type: string description: Lien identifier lienholder: $ref: '#/components/schemas/Lienholder' required: - lien_date - lienholder Address: type: object properties: recipient_name: type: string description: Name of the recipient at this address street1: type: string description: Primary street address line street2: type: string description: Secondary street address line (apartment, unit, etc.) city: type: string description: City name county: type: string description: County name state: type: string description: State abbreviation zip: type: string description: ZIP/postal code required: - street1 - city - state - zip SaleTypeEnum: type: string enum: - NEW - USED - GIFT description: Type of vehicle sale transaction Dealer: allOf: - $ref: '#/components/schemas/Entity' - type: object properties: type: type: string enum: - DEALERSHIP dealer_id: type: string dealer_tax_id: type: string required: - dealer_id AdditionalDues: type: object properties: fidelity: type: string enum: - initial - apiEstimate - final - actual deliveryEstimate: type: number taxEstimates: type: array items: $ref: '#/components/schemas/TransactionFee' feeEstimates: type: array items: $ref: '#/components/schemas/TransactionFee' required: - fidelity - deliveryEstimate - taxEstimates - feeEstimates VehicleBrandEnum: type: string enum: - SALVAGE - REBUILT - RECONSTRUCTED - DISMANTLED - JUNK - CRUSHED - EXPORT_ONLY - TOTALED - OWNER_RETAINED - PRIOR_OWNER_RETAINED - NON_REPAIRABLE_REPAIRED - SALVAGE_RETENTION - SALVAGE_OTHER - FLOOD - SALT_WATER_DAMAGE - FIRE_DAMAGE - LEMON - WARRANTY_RETURN - MANUFACTURER_BUYBACK - REPLICA - GRAY_MARKET - VIN_REPLACED - ACTUAL_MILEAGE - NOT_ACTUAL_MILEAGE - TAMPERING_VERIFIED - EXEMPT_ODOMETER - EXCEEDS_MECHANICAL_LIMITS - ODOMETER_ALTERED - ODOMETER_REPLACED - ODOMETER_DISCREPANCY - CARS_PENDING_JUNK - CARS_JUNK - MEMORANDUM_COPY - CALL_TITLE_DIVISION - PENDING_INVESTIGATION - UNKNOWN - NONE description: >- Vehicle title brand designation. Includes NMVTIS brands covering damage, environmental, manufacturer, odometer, and administrative categories. OdometerStatusEnum: type: string enum: - ACTUAL - NOT_ACTUAL - EXCESS - EXEMPT description: Odometer reading status Entity: type: object properties: id: type: string description: >- Use this field to pass your internal uuid for an entity, or let Cardinal Gray generate one type: type: string enum: - PERSON - DEALERSHIP - BUSINESS - LIENHOLDER description: Type of entity name: type: string description: >- Full name of owner in First Middle Last format. If found in Last, First Middle format, convert it name_first: type: string description: First name component name_middle: type: string description: Middle name component name_last: type: string description: Last name component name_suffix: type: string description: Name suffix (e.g., Jr., Sr., III) oats_names: type: array items: type: string description: >- Each additional name for the owner in First Middle Last format; do not confuse separate owners for an oats name description: >- Sometimes the same document can contain multiple names for the same person (i.e. the mailing info says Harper Smith but the section under titled or registered owners says John Smith-Avery), please list the additional names (in this case the former) in the oats_names array addr: $ref: '#/components/schemas/Address' description: Physical/residential address of the owner contact_phone: type: string description: Phone number for the owner contact_email: type: string description: Email address for the owner required: - type - name - addr DriversLicense: type: object properties: number: type: string description: Driver's license number state: type: string description: Two-letter code of state that issued the license sex: type: string description: Gender/sex as listed on license (typically 'M' or 'F') expiration_date: type: string description: License expiration date, format MM/DD/YYYY preferred first_name: type: string description: First name as it appears on license middle_name: type: string description: Middle name or initial as it appears on license last_name: type: string description: Last name as it appears on license suffix: type: string description: Name suffix (e.g., Jr., Sr., III) addr: $ref: '#/components/schemas/Address' description: Address as it appears on the driver's license required: - number - state - sex responses: Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Response' securitySchemes: bearerAuth: type: http scheme: bearer ````