> ## 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
Create a title entry from structured `account_data`, document URLs, or a raw array of document URLs. If an entry with the same VIN already exists for your organization, Porter updates the existing entry instead of creating a duplicate.
## Response Variants
This endpoint returns HTTP `200` for successful creates and updates.
Returned for new entries and for existing entries when enrichment is requested.
`pending` for new entries, or `enriching` when an existing VIN is updated and a sync flag was requested.
When an existing VIN is updated without sync flags, the API returns the full patched title entry instead of the minimal `{entryId, job_status}` response.
## Notes
* A raw JSON array is accepted as a legacy shorthand for `{ "attachments": [...] }`.
* If `sync_public` or `sync_private` is requested without an issuing state, the API automatically enables `sync_nmvtis`.
* `dppa_exemption` is optional on create. When provided, it is passed through to enrichment requests.
## 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://api.cardinalzyn.com
description: Staging
- url: https://api.cardinalgray.com
description: Production
security:
- bearerAuth: []
- basicAuth: []
- cookieAuth: []
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: array
title: Raw Document URL Array
description: >-
Legacy shorthand: an array of document URLs is treated as {
attachments: [...] }
items:
type: string
format: uri
minItems: 1
maxItems: 10
example:
- https://example.com/title.pdf
- https://example.com/drivers-license.jpg
- 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: >-
Title entry created or existing entry updated. The response variant
depends on VIN deduplication and requested sync flags.
content:
application/json:
schema:
oneOf:
- description: New entry created; job_status is pending
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
- $ref: 51776628-4d0b-454c-8f82-02196a84e1b3
description: >-
Existing VIN updated and enrichment requested; job_status
is enriching
- $ref: '#/components/schemas/DynamoDBEntry'
description: >-
Existing VIN updated without sync flags; returns the full
patched entry
'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. Passed through to
enrichment requests when provided; create requests do not validate
it as required.
website:
type: string
description: >-
Accepted for legacy clients but ignored; the organization is derived
from authentication.
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'
txn_quick_reference:
$ref: '#/components/schemas/TxnQuickReference'
description: Quick transaction classification used to route title workflows
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
DynamoDBEntry:
type: object
properties:
webhook_events:
type: array
items:
type: string
description: >-
Only exists on sent webhooks to help users quickly parse specific
fields
website:
type: string
description: Organization identifier
entryId:
type: string
description: Unique identifier for this database entry
userId:
type: string
description: User who created this entry
user_email:
type: string
description: Email of the user who created this entry
job_status:
$ref: '#/components/schemas/JobStatus'
description: Processing status of the job
createdAt:
description: >-
Timestamp when this entry was created. Stored loosely by the API and
may be a number, string, or date-like value.
processingStartTime:
type: number
description: Epoch timestamp when processing started
groupId:
type: string
description: User group ID for organizational access control
s3Index:
type: string
description: S3 path prefix for this entry's documents
last_modified:
type: number
description: Timestamp when this entry was last modified
processingTimeMs:
type: number
description: Total processing duration in milliseconds
VIN:
type: string
description: Vehicle Identification Number (17 characters)
state:
type: string
description: State where the vehicle is titled/registered
Borrower:
type: string
description: Primary borrower name on the loan
existingEntryId:
type: string
description: If this is a duplicate entry, points to the original entry ID
bdaJobs:
type: object
additionalProperties:
type: string
description: Background document analysis job statuses
private_enrichment_pending:
type: boolean
description: >-
Whether a private enrichment job has been enqueued and is still
pending
attachment:
type: array
items:
$ref: '#/components/schemas/DocumentUpload'
description: User-uploaded documents like driver licenses, vehicle titles, etc.
lmsData:
type: object
description: Loan management system data
loanData:
description: Legacy loan data field (can be any type or AccountData)
oneOf:
- $ref: '#/components/schemas/AccountData'
- type: object
account_data:
$ref: '#/components/schemas/AccountData'
account_status:
$ref: '#/components/schemas/AccountStatus'
description: Account status to determine workflows (scrapers, etc.)
is_elt:
type: boolean
description: Whether this account uses Electronic Lien & Title system
elt_data:
$ref: '#/components/schemas/DynamoEltData'
lenderLoanId:
type: string
description: Lender's internal loan/account number
tracking_url_provider:
type: string
description: Service provider for shipping tracking (if applicable)
form_statement_of_fact:
type: string
description: S3 path to the Statement of Fact form PDF
form_lien_add:
type: string
description: S3 path to the Add Lien form PDF
form_title_application:
type: string
description: S3 path to the Title Application form PDF
form_duplicate_title:
type: string
description: S3 path to the Duplicate Title request form PDF
form_repo_affidavit:
type: string
description: S3 path to the Repossession Affidavit PDF
form_lien_release_letter:
type: string
description: S3 path to the Lien Release Letter PDF
forms_poa:
type: array
items:
$ref: '#/components/schemas/FormAndGeneric'
description: Array of Power of Attorney forms
form_payoff_authorization:
type: string
description: S3 path to the Payoff Authorization form PDF
form_letter_of_guarantee:
type: string
description: S3 path to the Letter of Guarantee PDF
form_final_packet:
type: string
description: >-
S3 path to the Final Packet PDF (contains all generated forms
combined)
form_title_delivery:
type: string
description: S3 path to the title delivery form PDF
form_ucc1:
type: string
description: S3 path to the UCC-1 form PDF
final_packet_indices:
type: string
description: >-
Page indices showing which forms appear on which pages of the final
packet
form_instructions:
type: string
description: S3 path to the Instructions PDF
form_ohv_declaration:
type: string
description: S3 path to the Off-Highway Vehicle Declaration PDF
form_odometer_disclosure:
type: string
description: S3 path to the Odometer Disclosure form PDF
form_addr_oats:
type: string
description: S3 path to the Address OATS form PDF
form_vin_verification:
type: string
description: S3 path to the VIN Verification form PDF
form_low_speed_affidavit:
type: string
description: S3 path to the Low Speed Vehicle Affidavit PDF
forms_name_oats:
type: array
items:
$ref: '#/components/schemas/FormAndGeneric'
description: Array of Name OATS forms
forms_non_obligor:
type: array
items:
$ref: '#/components/schemas/FormAndGeneric'
description: Array of Non-Obligor forms
form_updates:
type: object
additionalProperties:
type: string
description: >-
Mapping of DynamoDBEntry.form* key to s3 metadata.json file
containing overview of form updates
form_downloads:
type: object
additionalProperties:
type: number
description: Mapping of DynamoDBEntry.form* key to download count
forms_status:
$ref: '#/components/schemas/FormsStatus'
description: Latest form generation status for this title entry
nmvtis_txn_id:
type: string
description: Transaction ID for NMVTIS vehicle history report
nmvtis_pull:
type: string
description: >-
S3 URL to JSON file containing the NMVTIS pull results as
AccountData
nmvtis_found_status:
$ref: '#/components/schemas/DataPullStatus'
description: >-
NMVTIS pull status: 'found' (record exists), 'not_found' (no
record), 'error' (CG failure, retry), 'unavailable' (source down)
nmvtis_report_pdf:
type: string
description: S3 path to the NMVTIS vehicle history report PDF
nmvtis_last_fetch:
type: string
description: Timestamp of last NMVTIS data fetch
state_txn_id:
type: string
description: Transaction ID for state DMV data pull (Yassi, DMV123, or internal)
state_pull:
type: string
description: >-
S3 URL to JSON file containing the state DMV pull results as
AccountData
state_found_status:
$ref: '#/components/schemas/DataPullStatus'
description: >-
State DMV pull status: 'found' (record exists), 'not_found' (no
record), 'error' (CG failure, retry), 'unavailable' (source down)
state_report_pdf:
type: string
description: S3 path to the state DMV report PDF
state_last_fetch:
type: string
description: Timestamp of last state DMV data fetch
portal_screenshot:
type: string
description: >-
S3 path to a screenshot of the DMV portal showing current vehicle
status
portal_pull:
type: string
description: >-
S3 URL to JSON file containing the DMV portal pull results as
AccountData
portal_found_status:
$ref: '#/components/schemas/DataPullStatus'
description: >-
DMV portal pull status: 'found' (record exists), 'not_found' (no
record), 'error' (CG failure, retry), 'unavailable' (portal down)
portal_last_fetch:
type: string
description: Timestamp of last DMV portal data fetch
public_pull:
type: string
description: >-
S3 URL to JSON file containing public enrichment results as
AccountData
public_report_pdf:
type: string
description: S3 path to the public enrichment report PDF
public_found_status:
$ref: '#/components/schemas/DataPullStatus'
description: Public enrichment pull status
public_txn_id:
type: string
description: Transaction ID for public enrichment
public_last_fetch:
type: string
description: Timestamp of last public enrichment data fetch
sftp_exported_at:
type: number
description: Epoch timestamp when this entry was exported over SFTP
insurance_last_fetch:
type: string
format: date-time
description: Timestamp of last insurance data fetch
insurance_search_raw_data:
type: object
description: Raw insurance search data
insurance_search_result:
type: string
description: Insurance search result status
insurance_update_result:
type: string
description: Insurance update result status
title_collection:
$ref: '#/components/schemas/TitleCollection'
signature_requests:
type: array
items:
$ref: '#/components/schemas/SignatureRequest'
description: >-
Electronic signature requests including signed documents,
certificates, and collected driver licenses
fee_estimate:
$ref: '#/components/schemas/EstFees'
submission_id:
type: string
description: Submission workflow identifier associated with this title entry
account_discrepancies:
type: object
deprecated: true
description: >-
Deprecated. Discrepancies found between different data sources
(document uploads, NMVTIS, state portals, etc.) for this account.
Each discrepancy shows field path and conflicting values with their
sources.
properties:
items:
type: array
description: List of field discrepancies found across data sources
items:
type: object
properties:
field_path:
type: string
description: >-
JSON pointer path to the conflicting field (e.g.
'/vehicle/title/issuance_date')
observations:
type: array
description: >-
All different values found for this field from various
sources
items:
type: object
properties:
from:
type: object
description: Source of this data value
properties:
kind:
type: string
enum:
- document_upload
- state_portal_pull
- nmvtis_pull
description: Type of data source
ref_id:
type: string
description: >-
Reference ID for the source (S3 key, transaction
ID, etc.)
doc_type:
type: string
description: >-
Document type if source is document_upload (e.g.
VEHICLE_TITLE, DRIVER_LICENSE)
value:
description: The actual value found from this source
account_matches:
type: object
deprecated: true
description: >-
Deprecated. Fields where multiple data sources agree on the same
value, providing validation confidence for critical data points like
title numbers, dates, etc.
properties:
items:
type: array
description: List of fields where all data sources agree
items:
type: object
properties:
field_path:
type: string
description: >-
JSON pointer path to the matching field (e.g.
'/vehicle/title/issuance_date')
agreed_value:
description: The normalized value that all sources agree on
sources:
type: array
description: All data sources that provided this matching value
items:
type: object
properties:
kind:
type: string
enum:
- document_upload
- state_portal_pull
- nmvtis_pull
description: Type of data source
ref_id:
type: string
description: >-
Reference ID for the source (S3 key, transaction ID,
etc.)
doc_type:
type: string
description: >-
Document type if source is document_upload (e.g.
VEHICLE_TITLE, DRIVER_LICENSE)
account_facts:
$ref: '#/components/schemas/AccountFacts'
description: >-
Preview / not-GA. Crystallized yes/no judgements for title review,
derived from the reconcile engine. Returned only for eligible
preview organizations when job_status is complete.
enrichment_slack_channel_id:
type: string
description: Slack channel ID for the enrichment thread
enrichment_slack_message_ts:
type: string
description: Slack message timestamp for the enrichment thread
enrichment_slack_thread_started_at:
type: number
description: Epoch timestamp when the enrichment Slack thread was started
required:
- website
- entryId
- userId
- job_status
- s3Index
- createdAt
- VIN
- state
- Borrower
- attachment
- loanData
- account_data
- account_status
- lenderLoanId
- tracking_url_provider
Response:
type: object
properties:
error:
type: string
description: Error message
statusCode:
type: number
description: >-
HTTP status code. Present on selected success responses, such as
DELETE /title/{id}.
disallowedFields:
type: array
items:
type: string
description: >-
Fields rejected by PATCH /title/{id} when attempting to modify
restricted top-level fields
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
- CANCELLED
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
- BRAND
- 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
TxnQuickReference:
type: string
enum:
- refi
- free_clear
- leasebuyout
- sale_p2p
- sale_dealer
description: Quick transaction classification used to route title workflows
DocumentUpload:
type: object
properties:
display_name:
type: string
description: Human-readable name for this document
s3_key:
type: string
description: S3 key for accessing the document
document_type:
type: string
enum:
- VEHICLE_TITLE
- VEHICLE_TITLE_BACK
- VEHICLE_REGISTRATION
- DRIVER_LICENSE
- DRIVER_LICENSE_BACK
- PAYOFF_LETTER
- UNKNOWN
- MARRIAGE_DIVORCE_NAMECHANGE_CERT
- SECURITY_AGREEMENT
- ASSET_RECOVERY_REPO_REPORT
- AUTO_INSURANCE_COVERAGE_CARD
- LOS_INPUT
description: Type of document that was uploaded
json_path:
type: string
description: Filepath to Partial.json file in S3
required:
- display_name
- s3_key
- document_type
AccountStatus:
type: string
enum:
- originated
- poa_sent
- poa_signed
- filing_en_route
- filing_received
- lien_delay
- lien_error
- lien_filed
- lien_perfected
- account_paid
- lien_release_pending
- lien_release_complete
description: >-
Current status of the account in the titling/lien workflow. Early
stages: 'originated' - Account created; 'poa_sent' - Power of Attorney
sent to customer; 'poa_signed' - POA signed and returned. DMV
submission: 'filing_en_route' - Documents in transit to DMV;
'filing_received' - DMV received documents. Lien lifecycle: 'lien_delay'
- Lien processing delayed; 'lien_error' - Error in lien filing;
'lien_filed' - DEPRECATED; 'lien_perfected' - Lien successfully
perfected. End of life: 'account_paid' - Account paid off;
'lien_release_pending' - Lien release in progress;
'lien_release_complete' - Lien fully released
DynamoEltData:
type: object
properties:
id:
type: string
description: Corresponds to elt system's txn id
ddi_email:
type: string
receipt_lien_perfection:
type: string
description: Corresponds to ELT_Perfection_Receipt
receipt_lien_release:
type: string
description: Corresponds to DDI ELT Lien Release Acknowledgement
receipt_lien_release_complete:
type: string
description: Corresponds to DDI ELT Lien Release Confirmation
release_rejection_reason:
type: string
description: Reason provided when an ELT lien release was rejected
release_rejection_date:
type: string
description: Date an ELT lien release rejection was recorded
messages:
type: array
items:
type: object
properties:
message:
$ref: '#/components/schemas/IndividualMessage'
resolved:
type: boolean
required:
- id
FormAndGeneric:
type: object
properties:
signer_id:
type: string
signer_name:
type: string
form:
type: string
form_generic:
type: string
required:
- signer_name
- form_generic
FormsStatus:
type: string
enum:
- generated
- skipped_no_data
- skipped_no_spec
- skipped_no_state
- error
description: Form generation status for a title entry
DataPullStatus:
type: string
enum:
- pending
- found
- not_found
- error
- unavailable
- skipped
description: >-
Status of data pull operations. 'pending' - enrichment enqueued; 'found'
- record exists; 'not_found' - no record; 'error' - CG failure, retry;
'unavailable' - source down; 'skipped' - source unavailable or not
applicable
TitleCollection:
type: object
description: >-
Physical title return guidance. Present when the organization is
enrolled in physical title collection and the title's signing state
requires the original paper title to be shipped back to Cardinal Gray
(e.g. Texas). Additive and may be absent — clients must tolerate its
absence. Created at most once per title: repeated sign actions and
retries return the same collection_id rather than creating a new
collection.
properties:
collection_id:
type: string
format: uuid
description: >-
Stable identifier for this title's collection. Does not change
across retries or repeated sign requests.
mode:
type: string
enum:
- STUB
- LIVE
description: >-
Fulfillment mode: LIVE is a real, trackable UPS shipment; STUB is
the sandbox experience (sample non-postage label, null
tracking_number, no qr_url). The field contract is identical in both
modes.
carrier:
type: string
enum:
- UPS
description: Shipping carrier for the title return.
service:
type: string
description: Carrier service used, e.g. "UPS Electronic Return Label".
tracking_number:
type: string
nullable: true
description: >-
Carrier tracking number. Null until a carrier shipment exists.
Clients must handle null.
label_url:
type: string
format: uri
description: >-
URL of the printable UPS return label. The guaranteed printable
fallback when present. In sandbox (STUB) responses this renders a
UPS sample label that is not valid postage.
qr_url:
type: string
format: uri
description: >-
Optional URL of a UPS mobile drop-off QR barcode. Present only when
qr_verified is true. Clients must not assume this field exists.
qr_verified:
type: boolean
description: >-
True only when qr_url is a verified UPS mobile drop-off barcode
accepted at UPS locations.
assets_expires_at:
type: string
format: date-time
description: >-
Expiry of the presigned label/QR asset URLs. Do not cache asset URLs
indefinitely.
return_address:
type: string
description: Postal address the original title must be returned to.
instructions:
type: array
items:
type: string
description: Ordered, human-readable instructions to present to the borrower.
created_at:
type: string
format: date-time
description: When the collection was created.
required:
- collection_id
- mode
- carrier
- service
- return_address
- instructions
- created_at
SignatureRequest:
type: object
properties:
transaction_access_url:
type: string
format: uri
readOnly: true
description: >-
Top-level transaction URL. Only populated after an explicit activate
action on a DRAFT Notarize/Proof request. For the initial create
response, look at each signer's transaction_access_url instead.
redirect_url:
type: object
properties:
url:
type: string
message:
type: string
required:
- url
requester_email:
type: string
description: Additional notification email for signature completion
id:
type: string
description: >-
Provider-specific ID (NTRZ::id for Notarize, DSGN::id for DocuSign,
DMNS::id for Documenso, PNDC::id for Pandadoc)
type:
type: string
enum:
- WET_SIGN
- WET_NOTARY
- RON
- E_SIGN
- NONE
description: Type of signature required
status:
type: string
enum:
- DRAFT
- SENT
- OPENED
- COMPLETED
- FAILED
- EXPIRED
description: Current status of the signature request
documents_to_sign:
type: array
items:
$ref: '#/components/schemas/DocumentToSign'
created_at:
type: string
description: When the request was created
updated_at:
type: string
description: Last status update
signers:
type: array
description: >-
Signers on this request. In the response from POST /title/{id}/sign,
each signer object includes a transaction_access_url field with the
per-signer signing link (Notarize/Proof provider only).
items:
$ref: '#/components/schemas/Person'
sign_cert:
type: string
description: S3 path to signing certification
collected_dlid:
type: string
description: S3 path to collected driver license ID
full_export:
type: string
description: >-
S3 path to full export consisting of sign cert, collected_dlid, and
documents_to_sign
physical_tracking:
type: object
properties:
status:
type: string
tracking_url:
type: string
label_url:
type: string
shipment_id:
type: string
return_tracking_url:
type: string
return_label_url:
type: string
return_shipment_id:
type: string
instructions:
type: string
description: Any special instructions for the signer
metadata:
type: object
additionalProperties: true
description: Additional provider-specific metadata
EstFees:
type: object
properties:
tax:
type: object
properties:
taxable_amount:
type: number
total:
type: number
items:
type: array
items:
$ref: '#/components/schemas/TransactionFee'
submission_instructions:
$ref: '#/components/schemas/RemittanceInstructions'
required:
- taxable_amount
- total
- items
registration:
type: object
properties:
total:
type: number
items:
type: array
items:
$ref: '#/components/schemas/TransactionFee'
required:
- total
- items
title:
type: object
properties:
total:
type: number
items:
type: array
items:
$ref: '#/components/schemas/TransactionFee'
required:
- total
- items
submission_instructions:
$ref: '#/components/schemas/RemittanceInstructions'
required:
- tax
- registration
- title
- submission_instructions
AccountFacts:
type: object
description: >-
Crystallized judgements derived from the vehicle reconciliation engine.
Always a projection of a reconciliation — never computed from raw
account_data alone.
properties:
computed_at:
type: string
format: date-time
description: >-
ISO 8601 timestamp when the facts were derived (computed live on
read).
source:
type: string
enum:
- reconcile
description: Provenance of the judgements.
borrower_on_title:
allOf:
- $ref: '#/components/schemas/AccountFact'
description: >-
True when every submitted obligor borrower matches a reconciled
title owner (fuzzy name matching).
borrower_signature_only_needed_for_title:
allOf:
- $ref: '#/components/schemas/AccountFact'
description: >-
True when the title is OR-titled or wholly owned by the submitted
borrower(s), so the borrower's signature alone is sufficient.
has_problematic_brands:
allOf:
- $ref: '#/components/schemas/AccountFact'
description: >-
True when the title carries a title-impairing brand (e.g. salvage,
flood, junk). Odometer and administrative brands are excluded.
are_there_active_liens:
allOf:
- $ref: '#/components/schemas/AccountFact'
description: >-
True when at least one unreleased lien remains on the title, or when
has_liens is true without lien detail.
required:
- computed_at
- source
- borrower_on_title
- borrower_signature_only_needed_for_title
- has_problematic_brands
- are_there_active_liens
example:
computed_at: '2026-06-18T18:42:11.123Z'
source: reconcile
borrower_on_title:
value: true
summary: All 1 submitted borrower(s) (Thomas A. Lopez) match a title owner.
references:
- field_path: /loan/borrower/0/name
value: Thomas A. Lopez
from:
kind: submitted_borrower
ref_id: loan.borrower[0]
- field_path: /vehicle/title/owners
value:
- THOMAS LOPEZ
from:
kind: reconciled_title
borrower_signature_only_needed_for_title:
value: true
summary: >-
All title owners are the submitted borrower(s); the borrower's
signature alone is sufficient.
references:
- field_path: /vehicle/title/is_or
value: false
from:
kind: reconciled_title
- field_path: /vehicle/title/owners
value:
- THOMAS LOPEZ
from:
kind: reconciled_title
has_problematic_brands:
value: false
summary: No problematic title brands (e.g. salvage, flood, junk) were found.
references:
- field_path: /vehicle/title/brands
value: null
from:
kind: reconciled_title
are_there_active_liens:
value: false
summary: No active liens were found on the title.
references: []
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:
$ref: '#/components/schemas/FeeKind'
description: Type of fee (e.g., 'StateTax', 'TitleFee', 'RegFee')
name:
type: string
description: Human-readable name of the fee
description:
type: string
description: Human-readable description or source note for the fee
value:
type: number
description: Fee amount in dollars
metadata:
type: object
additionalProperties: true
description: Additional fee-specific metadata
relevant_transactions:
type: array
description: Transaction types or conditions for which this fee applies
items:
oneOf:
- type: string
- type: object
additionalProperties: true
max:
type: number
description: Maximum fee amount when the fee is capped
county:
type: string
description: County where this fee applies
city:
type: string
description: City where this fee applies
subtract:
type: boolean
description: Whether this fee should be subtracted from the total
src:
type: object
description: Source URL and retrieval date for the fee
properties:
url:
type: string
date:
type: string
late_conditions:
type: array
description: Conditions that cause this late fee to apply
items:
type: object
additionalProperties: true
last_updated:
type: string
description: Date the fee definition was last updated
required:
- feeType
- value
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)
prev_action_date:
type: string
description: Date associated with the previous title action
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
enum:
- registered_owner
- titled_owner
- co_owner
- lessor
- lessee
- debtor
- tod_beneficiary
description: Relationship this person has to the vehicle or transaction
is_nonobligor:
type: boolean
description: Whether this person is a non-obligor on the loan
transaction_access_url:
type: string
format: uri
readOnly: true
description: >-
Per-signer URL for accessing the signature transaction. Present
on signers in the response from POST /title/{id}/sign when the
provider is Notarize/Proof. Not applicable to DocuSign-based
requests.
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'
lien_release_signed:
type: boolean
description: >-
Whether the title document shows the prior lien was released or
acknowledged
lien_release_date:
type: string
description: Date shown for the prior lien release
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
signatory:
$ref: '#/components/schemas/Person'
description: Person authorized to sign on behalf of the dealership
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
IndividualMessage:
type: object
properties:
messageId:
type: string
messageType:
type: string
loanNumber:
type: string
vin:
type: string
documentId:
type: string
nullable: true
documentType:
type: string
nullable: true
messageContent:
type: string
eventDate:
type: string
responseExpected:
type: string
stateFee:
type: string
required:
- messageId
- messageType
- loanNumber
- vin
- documentId
- documentType
- messageContent
- eventDate
- responseExpected
DocumentToSign:
type: object
properties:
filename:
type: string
id:
type: string
signer_id:
type: array
items:
type: string
signed_copy:
type: string
RemittanceInstructions:
type: object
properties:
payable_to:
type: string
address:
$ref: '#/components/schemas/Address'
required:
- payable_to
- address
AccountFact:
type: object
description: >-
A single yes/no judgement with a plain-language explanation and
supporting references.
properties:
value:
type: boolean
description: >-
The judgement. For data-dependent facts, `false` can mean either a
genuine negative answer or that required inputs were absent (e.g. no
submitted borrowers or no reconciled owners). Use `summary` to
disambiguate.
summary:
type: string
description: >-
Human-readable one-liner explaining the judgement. Also
disambiguates a no-data `false` from a genuine negative.
references:
type: array
description: Supporting field paths and values used to reach the judgement.
items:
$ref: '#/components/schemas/AccountFactReference'
required:
- value
- summary
- references
FeeKind:
type: string
enum:
- StateTax
- TaxRate
- LateTaxRate
- LateTitleFee
- LateRegFee
- TitleFee
- TitleLienFee
- RegFee
- RegRate
- CountyDiff
- CityDiff
description: Kind of fee or rate represented by a transaction fee item
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
AccountFactReference:
type: object
description: >-
A pointer into account_data or reconciled title data supporting an
AccountFact judgement.
properties:
field_path:
type: string
description: >-
JSON pointer into account_data or reconciled vehicle data (e.g.
`/loan/borrower/0/name`, `/vehicle/title/owners`).
value:
description: The value observed at field_path when the fact was computed.
from:
type: object
description: Optional provenance for the reference.
properties:
kind:
type: string
enum:
- submitted_borrower
- reconciled_title
description: >-
Where the referenced value came from: the original POST /title
submission, or reconciled title data.
ref_id:
type: string
description: >-
Optional locator within the source (e.g. `loan.borrower[0]`,
`lien_date:01/20/2023`).
required:
- field_path
- value
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
description: 'API key or Clerk JWT supplied as Authorization: Bearer '
basicAuth:
type: http
scheme: basic
description: >-
Legacy API key authentication supplied with Authorization: Basic
cookieAuth:
type: apiKey
in: cookie
name: __session
description: Clerk session cookie authentication
````