{ "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": { "get": { "summary": "List title entries or search by parameters", "description": "Retrieves title entries for your organization. Supports filtering by state, modification date, account status, and VIN lookup. Can return aggregated state counts for mapping visualizations or paginated entry lists.", "parameters": [ { "$ref": "#/components/parameters/vin" }, { "$ref": "#/components/parameters/state" }, { "$ref": "#/components/parameters/timeline" }, { "$ref": "#/components/parameters/account_status" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/nextToken" }, { "$ref": "#/components/parameters/groupId" }, { "$ref": "#/components/parameters/stateMap" } ], "responses": { "200": { "description": "Successful response with different formats based on query parameters", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DynamoDBEntry", "description": "Single title entry with presigned URLs (returned when using ?vin parameter)" }, { "type": "object", "description": "Paginated collection of title entries (default response)", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DynamoDBEntry" }, "description": "Array of title entries matching the query criteria" }, "count": { "type": "integer", "description": "Number of items in this page", "example": 25 }, "nextToken": { "type": "string", "description": "Token for retrieving the next page of results (only present if more results available)", "nullable": true }, "hasMore": { "type": "boolean", "description": "Whether another page of results is available" } }, "required": [ "items", "count", "hasMore" ] }, { "type": "object", "description": "State-count map returned when using ?stateMap=true", "additionalProperties": { "type": "integer" }, "example": { "CA": 42, "TX": 17 } } ] } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "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": "#/paths/~1title~1%7Bid%7D~1data/post/responses/200/content/application~1json/schema", "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" } } } }, "/title/{id}": { "get": { "summary": "Retrieve a specific title entry", "description": "Retrieves a complete title entry by its unique ID, including associated document paths rewritten to pre-signed URLs for secure access. If the entry is a duplicate pointer, automatically resolves to the canonical entry. Preview organizations may also receive account_facts when the entry is complete.", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamoDBEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "summary": "Update a title entry", "description": "Updates a title entry with new account_data. Partner requests may only modify account_data; other fields return 403 with disallowedFields. Empty JSON objects are accepted as no-op updates and return the current merged entry.", "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "description": "Account data updates to apply to the title entry", "content": { "application/json": { "schema": { "type": "object", "properties": { "account_data": { "$ref": "#/components/schemas/AccountData", "description": "Partial or complete account data to merge with existing entry" } }, "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Title entry updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamoDBEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Forbidden update attempt", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response" }, { "type": "object", "properties": { "disallowedFields": { "type": "array", "items": { "type": "string" }, "description": "Fields that cannot be modified by partner PATCH requests" } } } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "summary": "Delete a title entry", "description": "Permanently deletes a title entry and all associated duplicate entries. This operation automatically handles cleanup of related entries that reference the deleted entry via existingEntryId.", "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Title entry and related entries deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "HTTP status code (200 for successful deletion)", "example": 200 }, "message": { "type": "string", "description": "Confirmation message indicating successful deletion", "example": "Entries deleted successfully" }, "entryId": { "type": "string", "description": "The ID of the primary deleted entry", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "deletedCount": { "type": "integer", "description": "Total number of entries deleted (including duplicates)", "example": 3 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ] } }, "/title/{id}/data": { "post": { "description": "Pull or update DMV/public data for an existing title entry. At least one of sync_nmvtis, sync_public, or sync_private must be true.", "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "description": "Data sources to fetch from. At least one sync flag must be true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync_nmvtis": { "type": "boolean", "description": "Fetch data from NMVTIS (National Motor Vehicle Title Information System)", "default": false }, "sync_public": { "type": "boolean", "description": "Fetch data from public DMV websites.", "default": false }, "sync_private": { "type": "boolean", "description": "Fetch vehicle title and registrant information from private DMV portals.", "default": false }, "dppa_exemption": { "type": "string", "description": "Driver's Privacy Protection Act exemption code passed through to private/NMVTIS enrichment requests when provided", "default": "legitimate_business_need" } }, "minProperties": 1 } } }, "required": true }, "responses": { "200": { "description": "Data enrichment or processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "entryId": { "type": "string", "description": "ID of the title entry being processed" }, "job_status": { "$ref": "#/components/schemas/JobStatus", "description": "Will be 'enriching' if successful, 'error' if failed", "example": "enriching" } }, "required": [ "entryId", "job_status" ] } } } }, "400": { "description": "Invalid request parameters or title entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Organization lacks necessary permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Title entry is missing account_data required for enrichment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ] } }, "/title/{id}/fees": { "post": { "summary": "Calculate fees for a title entry", "description": "Initiates fee calculation for a title entry based on the vehicle and transaction details. Returns job status while fees are calculated asynchronously.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the title entry" } ], "responses": { "200": { "$ref": "#/paths/~1title~1%7Bid%7D~1data/post/responses/200" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ] } }, "/title/{id}/forms": { "post": { "summary": "Generate forms for a title entry", "description": "Synchronously generates or regenerates forms for a title entry based on the account data and transaction type. Partner-facing requests use the default form generation behavior and return the entryId when complete.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the title entry" } ], "responses": { "200": { "description": "Forms generated or regenerated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "entryId": { "type": "string", "description": "ID of the title entry whose forms were generated" } }, "required": [ "entryId" ] } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ] } }, "/title/{id}/sign": { "post": { "description": "Create a signature request for generated title documents. Provide explicit signers and documents, or omit the request body to let the API build a request from current title owners/borrowers with contact_email values already present on the entry.", "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "description": "Customization options for the signature request (e.g., in cases where you don't want to collect signatures from all titled owners).", "content": { "application/json": { "schema": { "type": "object", "properties": { "signers": { "type": "array", "description": "List of specific people who should sign the documents. Each signer must include contact_email. If the body is omitted entirely, the API attempts to build signers from current owners/borrowers already stored on the entry.", "items": { "$ref": "#/components/schemas/Person" }, "minItems": 1 }, "documents_to_sign": { "type": "array", "description": "List of specific documents to be signed.", "items": { "$ref": "#/components/schemas/DocumentToSign" }, "minItems": 1 }, "redirect_url": { "description": "Optional redirect URL or redirect descriptor used by the signature provider after signing.", "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "message": { "type": "string" } }, "required": [ "url" ] } ] }, "requester_email": { "type": "string", "description": "Additional notification email for signature completion" }, "instructions": { "type": "string", "description": "Special instructions for the signer" } } } } }, "required": false }, "responses": { "200": { "description": "Signature request created successfully. For organizations enrolled in physical title collection, titles in states that require the original paper title to be returned (e.g. Texas) additionally include a title_collection object with return-shipping guidance.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignatureRequest" }, { "type": "object", "properties": { "title_collection": { "$ref": "#/components/schemas/TitleCollection" } } } ] } } } }, "400": { "description": "Missing required fields or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Organization lacks necessary permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ] } }, "/title/{id}/submit": { "post": { "summary": "Submit a title entry to the state", "description": "Submit a title entry to the DMV \u2014 either by mailing a physical packet (`MAIL` states) or by driving an online portal (`ONLINE_PORTAL` states). Which method is used, which supporting documents are required, and how the API responds are all determined by the entry's state.\n\nEvery attachment must include an `s3_key` (the S3 object key from Cardinal Gray's upload flow) and a `document_type`. `MAIL` states respond `200` with a presigned packet URL and the `checkAmount` / `checkPayee` to enclose. `ONLINE_PORTAL` states respond `202` \u2014 the submission runs in a background worker; poll `GET /title/{id}/submit/{submissionId}` for `status`, `applicationNumber`, and `confirmationImg`.\n\n**Managed submission mode.** Organizations enrolled in managed submission call this endpoint with **no request body** \u2014 the call is a signal that the loan is funded and Cardinal Gray should begin lien-perfection work. The API responds `202` with `intakeMode: \"MANAGED\"` and a durable `submissionId` whose status starts at `AWAITING_READINESS`; Cardinal Gray's title operations team selects the filing scenario, assembles documents, and files with the state. Repeated calls for the same title are idempotent and return the same `submissionId`. No `attachments` or `scenarioKey` are required, and the title's `account_status` does not change at intake \u2014 it advances only when filing actually occurs. Managed mode is enabled per organization by Cardinal Gray; contact support to enroll.", "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "required": false, "description": "Required for self-service organizations (`attachments` must be present). Managed-mode organizations omit the body entirely.", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachments": { "type": "array", "minItems": 1, "description": "Supporting documents included with the submission (title images, driver's license, signed power of attorney, lien release letter, etc.). Every item must have `s3_key` and `document_type`. **Required for self-service organizations; omitted in managed mode.**", "items": { "type": "object", "required": [ "s3_key", "document_type" ], "properties": { "s3_key": { "type": "string", "description": "S3 key of the uploaded document." }, "display_name": { "type": "string", "description": "Human-readable filename shown in the packet and follow-up emails." }, "document_type": { "type": "string", "description": "Document classification.", "enum": [ "VEHICLE_TITLE", "VEHICLE_TITLE_BACK", "DRIVER_LICENSE", "SIGNED_POWER_OF_ATTORNEY", "LIEN_RELEASE_LETTER", "COVER_SHEET", "UNKNOWN" ] }, "json_path": { "type": "string", "description": "Optional S3 key of the parsed JSON payload for this document." } } } }, "scenarioKey": { "type": "string", "description": "Submission scenario for this state (e.g. `CLEAR_TITLE`, `ACTIVE_LIEN`, `LOST_OR_ILLEGIBLE`, `REFINANCE_SECURED`, `LIEN_ADD`).\n\n**Required for `ONLINE_PORTAL` states** \u2014 an omitted or invalid `scenarioKey` returns `400 INVALID_SCENARIO_KEY` with the list of valid values for the state. Optional for `MAIL` states, where the API resolves the recommended scenario from the current account data." }, "coverSheetHints": { "type": "object", "description": "MAIL only. Overrides for the cover-sheet fields the API derives from the entry (owner list, borrower/lienholder names, ownership form, county).", "properties": { "ownerNames": { "type": "array", "items": { "type": "string" } }, "borrowerName": { "type": "string" }, "lienholderName": { "type": "string" }, "isAndTitle": { "type": "boolean", "description": "True when the title is joint (AND) rather than either-or (OR)." }, "ownerCount": { "type": "integer" }, "county": { "type": "string" } } }, "options": { "type": "object", "description": "Advanced overrides applied to generated forms in the packet.", "properties": { "formOverrides": { "type": "object", "properties": { "security_agreement_sign_date": { "type": "string", "description": "Override date printed on the security agreement (ISO 8601 or `MM/DD/YYYY`)." }, "check_number": { "type": "string", "description": "Check number to print on the cover sheet." } } } } } } } } } }, "responses": { "200": { "description": "Submission completed synchronously. Returned for `MAIL` states \u2014 the packet PDF has been generated and staged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitSuccess" } } } }, "202": { "description": "Submission accepted and queued. Returned for `ONLINE_PORTAL` states \u2014 a worker will drive the state portal in the background \u2014 and for managed-mode intake, where the response includes `intakeMode: \"MANAGED\"` and the submission starts at `AWAITING_READINESS`. Poll `GET /title/{id}/submit/{submissionId}` for status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitSuccess" } } } }, "400": { "description": "Missing or invalid attachments, unsupported state, or invalid `scenarioKey`. For managed-intake organizations, any non-empty request body returns 400 with \"Managed submission intake does not accept a request body\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ] } }, "/title/{id}/submit/{submissionId}": { "get": { "summary": "Get a submission", "description": "Fetch the current state of a submission, including the DMV/portal response, any application number, a presigned confirmation image (for portal submissions), and any feedback message attached to the submission.", "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "submissionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the submission returned by `POST /title/{id}/submit`." } ], "responses": { "200": { "description": "Current submission record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Submission" } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ] } } }, "components": { "schemas": { "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" } } }, "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" ] }, "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" ] }, "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" ] }, "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" ] } ] }, "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" ] } ] }, "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" } } } ] }, "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" }, "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" ] }, "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", "\n", "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" } } }, "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" } } }, "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" ] }, "DocumentToSign": { "type": "object", "properties": { "filename": { "type": "string" }, "id": { "type": "string" }, "signer_id": { "type": "array", "items": { "type": "string" } }, "signed_copy": { "type": "string" } } }, "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" } } }, "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 \u2014 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" ] }, "FormAndGeneric": { "type": "object", "properties": { "signer_id": { "type": "string" }, "signer_name": { "type": "string" }, "form": { "type": "string" }, "form_generic": { "type": "string" } }, "required": [ "signer_name", "form_generic" ] }, "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" ] }, "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" ] }, "FeeEstimate": { "allOf": [ { "$ref": "#/components/schemas/TransactionFee" } ], "deprecated": true, "description": "Deprecated alias for TransactionFee. Fee estimate arrays use TransactionFee items." }, "RemittanceInstructions": { "type": "object", "properties": { "payable_to": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" } }, "required": [ "payable_to", "address" ] }, "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" ] }, "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" ] }, "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" ] }, "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" ] }, "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" ] }, "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" } }, "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" ] }, "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" ] }, "AccountFacts": { "type": "object", "description": "Crystallized judgements derived from the vehicle reconciliation engine. Always a projection of a reconciliation \u2014 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": [] } } }, "UserGroup": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the user group" }, "name": { "type": "string", "description": "Group name (e.g., 'Central Titles', 'Arkansas Branch 69')" }, "users": { "type": "array", "items": { "type": "string" }, "description": "Array of user email addresses in this group" }, "preinit_email": { "type": "array", "items": { "type": "string" }, "description": "Array of emails that are pre-authorized for this group (auto-added without ***UNAUTHORIZED during signup)" }, "lienholder_data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Lienholder" }, "description": "Legacy field maintained for backward compatibility during migration. Lienholder configuration data keyed by state" }, "lienholder_data_s3_key": { "type": "string", "description": "S3-based storage for lienholder data (solves 400KB DynamoDB limit)" }, "group_mailbox": { "type": "array", "items": { "type": "string" }, "description": "Optional mailbox addresses for branch managers/notifications" }, "view": { "type": "object", "properties": { "restrict": { "type": "boolean", "description": "Whether to restrict view access" }, "linked_groups": { "type": "array", "items": { "type": "string" }, "description": "Array of linked group IDs" } }, "description": "View control settings" }, "feature_permissions": { "type": "object", "description": "Optional group-specific feature permissions. If not defined, inherits from parent ClientDBEntry permissions", "properties": { "useYassi": { "type": "boolean" }, "useScraper": { "type": "boolean" }, "useNotarize": { "type": "boolean" }, "useDocusign": { "type": "boolean" }, "useELT": { "type": "boolean" }, "useShipping": { "type": "boolean" }, "useFeeEstimates": { "type": "boolean", "description": "Optional for backward compatibility" }, "useSubmission": { "type": "boolean", "description": "Whether this group can use submission workflows" } } } }, "required": [ "id", "name", "users" ] }, "ClientDBEntry": { "type": "object", "properties": { "website": { "type": "string", "description": "Organization domain identifier" }, "informalName": { "type": "string", "description": "Human-readable organization name" }, "emailToIdentityId": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Mapping of email addresses to user identity IDs" }, "user_groups": { "type": "array", "items": { "$ref": "#/components/schemas/UserGroup" }, "description": "User groups within the organization" }, "admin_users": { "type": "array", "items": { "type": "string" }, "description": "Array of admin user email addresses" }, "useYassi": { "type": "boolean", "description": "Whether organization can use Yassi DMV data service" }, "useScraper": { "type": "boolean", "description": "Whether organization can use web scraping features" }, "useNotarize": { "type": "boolean", "description": "Whether organization can use Notarize service" }, "useDocusign": { "type": "boolean", "description": "Whether organization can use DocuSign integration" }, "useELT": { "type": "boolean", "description": "Whether organization can use Electronic Lien & Title" }, "useShipping": { "type": "boolean", "description": "Whether organization can use shipping features" }, "useFeeEstimates": { "type": "boolean", "description": "Whether organization can use fee estimates (optional for backward compatibility)" }, "useSubmission": { "type": "boolean", "description": "Whether organization can use submission workflows" }, "monthlyVolume": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Monthly transaction volume statistics" }, "totalLoansHandled": { "type": "object", "properties": { "value": { "type": "number" }, "lastUpdated": { "type": "string" }, "lastRecalculated": { "type": "string" } }, "description": "Total loans processed tracking" }, "docusign_profile": { "type": "object", "properties": { "account_id": { "type": "string" }, "client_id": { "type": "string" }, "user_id": { "type": "string", "description": "Required for JWT flow - DocuSign user ID who consented to the integration" }, "s3_private_key_path": { "type": "string", "description": "S3 key for JWT private key (format: '{website}/{filename}.pem')" }, "access_token": { "type": "string" }, "token_expiry": { "type": "number" } }, "required": [ "account_id", "client_id", "user_id", "s3_private_key_path" ] }, "ddi_profile": { "type": "array", "description": "Array to account for multiple ELT profiles (e.g., MF Kora). Object for tracking user ELT profile & automated job statuses", "items": { "type": "object", "properties": { "credentials": { "type": "object", "properties": { "url": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "partner_id": { "type": "string" } }, "required": [ "url", "email", "password", "partner_id" ] }, "notification_job": { "type": "object", "properties": { "last_run": { "type": "string" }, "status": { "type": "string" }, "notifs_handled": { "type": "number" } } }, "perfection_job": { "type": "object", "properties": { "last_run": { "type": "string" }, "status": { "type": "string" }, "liens_handled": { "type": "number" } } } }, "required": [ "credentials" ] } }, "payoffee_profile": { "type": "object", "properties": { "payoff_address": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" } }, "required": [ "name", "address" ] }, "insurance_credentials": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" }, "clientId": { "type": "string" } } } } } } }, "apiKeys": { "type": "array", "items": { "type": "string" }, "description": "API keys for organization" }, "apiKeyToUserId": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional mapping to choose a specific userId per API key (otherwise fallback behavior applies)" }, "webhook_profile": { "type": "object", "properties": { "url": { "type": "string", "description": "Webhook URL for organization events" }, "x_partner_key": { "type": "string", "description": "Optional partner key for webhook authentication" }, "authorization_token": { "type": "string", "description": "Optional authorization token for webhook authentication" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "title.job_status.complete", "title.job_status.error", "title.data.found", "title.data.not_found", "title.account_status.*" ] }, "description": "Array of webhook event types to subscribe to" } }, "required": [ "url", "events" ] }, "slack_channel_ids": { "type": "array", "items": { "type": "string" }, "description": "Slack channel IDs for notifications" }, "slack_channel_for_internal_alerts": { "type": "string", "description": "Slack channel used for internal alert notifications" } }, "required": [ "website", "informalName", "emailToIdentityId", "user_groups", "useYassi", "useScraper", "useNotarize", "useDocusign", "useELT", "useShipping", "apiKeys" ] }, "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" }, "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" }, "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" }, "VehicleUseEnum": { "type": "string", "enum": [ "PRIVATE", "COMMERCIAL" ], "description": "Vehicle use classification. PRIVATE for personal use, COMMERCIAL for business use" }, "SaleTypeEnum": { "type": "string", "enum": [ "NEW", "USED", "GIFT" ], "description": "Type of vehicle sale transaction" }, "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" }, "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" }, "FormsStatus": { "type": "string", "enum": [ "generated", "skipped_no_data", "skipped_no_spec", "skipped_no_state", "error" ], "description": "Form generation status for a title entry" }, "TxnQuickReference": { "type": "string", "enum": [ "refi", "free_clear", "leasebuyout", "sale_p2p", "sale_dealer" ], "description": "Quick transaction classification used to route title workflows" }, "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" }, "SubmissionMethod": { "type": "string", "enum": [ "MAIL", "ONLINE_PORTAL" ], "description": "How Cardinal Gray delivers the submission to the state. `MAIL` states return a packet PDF for the user to print and mail; `ONLINE_PORTAL` states are driven programmatically by a background worker." }, "SubmissionStatus": { "type": "string", "enum": [ "AWAITING_READINESS", "PENDING", "SUBMITTED", "UNDER_REVIEW", "ACTION_REQUIRED", "ACCEPTED", "REJECTED", "CANCELED", "ERROR" ], "description": "Lifecycle status of a submission. `AWAITING_READINESS` is the initial status of a managed-mode intake request \u2014 Cardinal Gray's title operations team is preparing the filing; `method` is absent until a filing path is selected. `ACTION_REQUIRED` means the state or review team has requested follow-up documents; see `feedbackMessage` for the explanation and reach out to Cardinal Gray support to submit the additional paperwork." }, "SubmitDocumentType": { "type": "string", "enum": [ "VEHICLE_TITLE", "VEHICLE_TITLE_BACK", "DRIVER_LICENSE", "SIGNED_POWER_OF_ATTORNEY", "LIEN_RELEASE_LETTER", "COVER_SHEET", "UNKNOWN" ], "description": "Classification for a supporting document included with a submission." }, "SubmitSuccess": { "type": "object", "required": [ "ok", "submissionId", "entryId", "state" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "submissionId": { "type": "string", "format": "uuid" }, "entryId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "description": "Two-letter state code the submission targets (e.g. `KS`, `FL`)." }, "method": { "$ref": "#/components/schemas/SubmissionMethod" }, "intakeMode": { "type": "string", "enum": [ "MANAGED" ], "description": "Present when the organization uses managed submission mode. `method` is absent on managed intake responses \u2014 Cardinal Gray selects the filing path during fulfillment." }, "confirmationImg": { "type": "string", "format": "uri", "description": "Presigned URL to a PNG confirmation screenshot captured from the state portal. `ONLINE_PORTAL` only." }, "applicationNumber": { "type": "string", "description": "Application/tracking number returned by the state portal, when available." }, "packetUrl": { "type": "string", "format": "uri", "description": "Presigned URL to the generated mail packet PDF. `MAIL` only." }, "packetS3Key": { "type": "string", "description": "S3 key for the mail packet PDF. `MAIL` only." }, "checkAmount": { "type": "number", "description": "Dollar amount to write on the enclosed check. `MAIL` only." }, "checkPayee": { "type": "string", "description": "Payee for the enclosed check. `MAIL` only." } } }, "Submission": { "type": "object", "required": [ "submissionId", "status" ], "properties": { "submissionId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/SubmissionStatus" }, "method": { "$ref": "#/components/schemas/SubmissionMethod" }, "intakeMode": { "type": "string", "enum": [ "MANAGED" ], "description": "Present on managed-mode submissions. While the submission is `AWAITING_READINESS`, `method` is absent \u2014 it appears once Cardinal Gray selects the filing path." }, "applicationNumber": { "type": "string", "description": "Application/tracking number returned by the state portal, when available." }, "confirmationImg": { "type": "string", "format": "uri", "description": "Presigned URL to a PNG screenshot captured from the state portal." }, "error": { "type": "string", "description": "Error message if the submission failed." }, "feedbackMessage": { "type": "string", "description": "Feedback surfaced from the state portal or review team \u2014 typically an explanation when `status` is `REJECTED` or `ACTION_REQUIRED`." }, "followUps": { "type": "array", "description": "Rounds of follow-up documents attached to this submission after the initial POST \u2014 each entry records when the documents were uploaded, the `feedbackMessage` they respond to, and the attachments themselves.", "items": { "type": "object", "required": [ "uploadedAt", "respondingTo", "attachments" ], "properties": { "uploadedAt": { "type": "string", "format": "date-time" }, "respondingTo": { "type": "string", "description": "The `feedbackMessage` this follow-up round is responding to." }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "s3_key", "document_type" ], "properties": { "s3_key": { "type": "string" }, "display_name": { "type": "string" }, "document_type": { "type": "string" } } } } } } } } } }, "parameters": { "id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the title entry" }, "vin": { "name": "vin", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "1HGBH41JXMN109186" }, "description": "Vehicle Identification Number (vin) to search for. Returns a single matching entry if found. Must be exactly 17 characters." }, "state": { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter entries by a specific US state" }, "timeline": { "name": "timeline", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 86400000 }, "description": "Filter entries modified within this many milliseconds from now (e.g., 86400000 for last 24 hours)" }, "account_status": { "name": "account_status", "in": "query", "required": false, "schema": { "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": "Filter entries by account status in the title workflow" }, "limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "example": 50 }, "description": "Maximum number of entries to return for pagination" }, "nextToken": { "name": "nextToken", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination token from previous response to get next page of results" }, "groupId": { "name": "groupId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter entries by specific group ID" }, "stateMap": { "name": "stateMap", "in": "query", "required": false, "schema": { "type": "boolean", "example": true }, "description": "When true, returns counts grouped by title state instead of a paginated entry list" } }, "responses": { "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "NotFound": { "description": "Not found", "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" } } } }