Submit Title Entry

curl -X POST "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarioKey": "CLEAR_TITLE",
    "attachments": [
      {
        "s3_key": "private/acme/entry-abc/title-front.pdf",
        "display_name": "Title front",
        "document_type": "VEHICLE_TITLE"
      },
      {
        "s3_key": "private/acme/entry-abc/title-back.pdf",
        "display_name": "Title back",
        "document_type": "VEHICLE_TITLE_BACK"
      },
      {
        "s3_key": "private/acme/entry-abc/dl.pdf",
        "display_name": "Driver license",
        "document_type": "DRIVER_LICENSE"
      }
    ]
  }'

curl -X POST "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarioKey": "LIEN_ADD",
    "attachments": [
      {
        "s3_key": "private/acme/entry-abc/title-front.pdf",
        "document_type": "VEHICLE_TITLE"
      },
      {
        "s3_key": "private/acme/entry-abc/spoa.pdf",
        "document_type": "SIGNED_POWER_OF_ATTORNEY"
      }
    ],
    "coverSheetHints": {
      "county": "Miami-Dade"
    }
  }'

{
  "ok": true,
  "submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
  "entryId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "KS",
  "method": "ONLINE_PORTAL"
}

{
  "ok": true,
  "submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
  "entryId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "TX",
  "intakeMode": "MANAGED"
}

{
  "ok": true,
  "submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
  "entryId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "FL",
  "method": "MAIL",
  "packetUrl": "https://s3.amazonaws.com/...&X-Amz-Signature=...",
  "packetS3Key": "private/acme/entry-abc/submit_packet.pdf",
  "checkAmount": 79.75,
  "checkPayee": "Florida Department of Highway Safety and Motor Vehicles"
}

POST

title

{id}

submit

curl -X POST "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarioKey": "CLEAR_TITLE",
    "attachments": [
      {
        "s3_key": "private/acme/entry-abc/title-front.pdf",
        "display_name": "Title front",
        "document_type": "VEHICLE_TITLE"
      },
      {
        "s3_key": "private/acme/entry-abc/title-back.pdf",
        "display_name": "Title back",
        "document_type": "VEHICLE_TITLE_BACK"
      },
      {
        "s3_key": "private/acme/entry-abc/dl.pdf",
        "display_name": "Driver license",
        "document_type": "DRIVER_LICENSE"
      }
    ]
  }'

curl -X POST "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarioKey": "LIEN_ADD",
    "attachments": [
      {
        "s3_key": "private/acme/entry-abc/title-front.pdf",
        "document_type": "VEHICLE_TITLE"
      },
      {
        "s3_key": "private/acme/entry-abc/spoa.pdf",
        "document_type": "SIGNED_POWER_OF_ATTORNEY"
      }
    ],
    "coverSheetHints": {
      "county": "Miami-Dade"
    }
  }'

{
  "ok": true,
  "submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
  "entryId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "KS",
  "method": "ONLINE_PORTAL"
}

{
  "ok": true,
  "submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
  "entryId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "TX",
  "intakeMode": "MANAGED"
}

{
  "ok": true,
  "submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
  "entryId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "FL",
  "method": "MAIL",
  "packetUrl": "https://s3.amazonaws.com/...&X-Amz-Signature=...",
  "packetS3Key": "private/acme/entry-abc/submit_packet.pdf",
  "checkAmount": 79.75,
  "checkPayee": "Florida Department of Highway Safety and Motor Vehicles"
}

Cardinal Gray submits title work to the state on your behalf. Depending on the entry’s state, submissions run in one of two modes:

MAIL — The API synchronously builds a mail packet (cover sheet, forms, and your uploaded documents merged into a single PDF), returns a presigned packetUrl, and tells you the checkAmount and checkPayee to enclose. You print, sign checks, and mail.
ONLINE_PORTAL — The API accepts the submission (202) and a background worker drives the state portal. Poll GET /title/{id}/submit/{submissionId} for status and the confirmation screenshot.

Managed submission mode

Organizations enrolled in managed submission use this endpoint differently: the call is a funding-complete signal, not a packet builder. Send the request with no body — no attachments, no scenarioKey. Cardinal Gray’s title operations team selects the filing scenario, assembles the documents, and files with the state on your behalf.

The API responds 202 with intakeMode: "MANAGED" and a durable submissionId.
The submission starts at status AWAITING_READINESS; poll GET /title/{id}/submit/{submissionId} to track it. method appears once Cardinal Gray selects the filing path.
Repeated calls for the same title are idempotent — you get the same submissionId back, and no duplicate filing work is started.
The title’s account_status does not change at intake; it advances only when filing actually occurs.

Managed mode is enabled per organization by Cardinal Gray — contact support to enroll. The sections below apply to self-service organizations only.

Attachments

Every attachment must include an s3_key and a document_type. Cardinal Gray issues presigned upload URLs through the dashboard’s document upload flow; the returned S3 keys are what you pass here. Supported document_type values:

VEHICLE_TITLE, VEHICLE_TITLE_BACK
DRIVER_LICENSE
SIGNED_POWER_OF_ATTORNEY
LIEN_RELEASE_LETTER
COVER_SHEET
UNKNOWN

Scenario key

Each supported state exposes one or more submission scenarios (e.g. CLEAR_TITLE, ACTIVE_LIEN, LOST_OR_ILLEGIBLE, REFINANCE_SECURED, LIEN_ADD).

ONLINE_PORTAL states — scenarioKey is required. An omitted or invalid value returns 400 with an INVALID_SCENARIO_KEY error listing the valid keys for the state.
MAIL states — scenarioKey is optional. The API resolves the recommended scenario from the entry’s current account data. Pass an explicit scenarioKey to override that choice.

Contact Cardinal Gray for the current scenario keys supported per state.

Response codes

200 OK

MAIL states

Packet generated and staged. Response includes packetUrl, packetS3Key, checkAmount, and checkPayee.

202 Accepted

ONLINE_PORTAL states / managed intake

Submission queued. Poll GET /title/{id}/submit/{submissionId} for status, applicationNumber, and confirmationImg. Managed-mode responses include intakeMode: "MANAGED" and no method.

400

Bad request

Missing attachments, an attachment missing s3_key or document_type, an unsupported state, or an invalid scenarioKey.

curl -X POST "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarioKey": "CLEAR_TITLE",
    "attachments": [
      {
        "s3_key": "private/acme/entry-abc/title-front.pdf",
        "display_name": "Title front",
        "document_type": "VEHICLE_TITLE"
      },
      {
        "s3_key": "private/acme/entry-abc/title-back.pdf",
        "display_name": "Title back",
        "document_type": "VEHICLE_TITLE_BACK"
      },
      {
        "s3_key": "private/acme/entry-abc/dl.pdf",
        "display_name": "Driver license",
        "document_type": "DRIVER_LICENSE"
      }
    ]
  }'

curl -X POST "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarioKey": "LIEN_ADD",
    "attachments": [
      {
        "s3_key": "private/acme/entry-abc/title-front.pdf",
        "document_type": "VEHICLE_TITLE"
      },
      {
        "s3_key": "private/acme/entry-abc/spoa.pdf",
        "document_type": "SIGNED_POWER_OF_ATTORNEY"
      }
    ],
    "coverSheetHints": {
      "county": "Miami-Dade"
    }
  }'

{
  "ok": true,
  "submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
  "entryId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "KS",
  "method": "ONLINE_PORTAL"
}

{
  "ok": true,
  "submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
  "entryId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "TX",
  "intakeMode": "MANAGED"
}

{
  "ok": true,
  "submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
  "entryId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "FL",
  "method": "MAIL",
  "packetUrl": "https://s3.amazonaws.com/...&X-Amz-Signature=...",
  "packetS3Key": "private/acme/entry-abc/submit_packet.pdf",
  "checkAmount": 79.75,
  "checkPayee": "Florida Department of Highway Safety and Motor Vehicles"
}

Authorizations

Authorization

string

header

required

API key or Clerk JWT supplied as Authorization: Bearer

Path Parameters

string

required

Unique identifier of the title entry

Body

application/json

Required for self-service organizations (attachments must be present). Managed-mode organizations omit the body entirely.

attachments

object[]

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.

Minimum array length: 1

Show child attributes

scenarioKey

string

Submission scenario for this state (e.g. CLEAR_TITLE, ACTIVE_LIEN, LOST_OR_ILLEGIBLE, REFINANCE_SECURED, LIEN_ADD).

Required for ONLINE_PORTAL states — 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

object

MAIL only. Overrides for the cover-sheet fields the API derives from the entry (owner list, borrower/lienholder names, ownership form, county).

Show child attributes

options

object

Advanced overrides applied to generated forms in the packet.

Show child attributes

Response

Submission completed synchronously. Returned for MAIL states — the packet PDF has been generated and staged.

enum<boolean>

required

Available options:

true

submissionId

string<uuid>

required

entryId

string<uuid>

required

state

string

required

Two-letter state code the submission targets (e.g. KS, FL).

method

enum<string>

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.

Available options:

MAIL,

ONLINE_PORTAL

intakeMode

enum<string>

Present when the organization uses managed submission mode. method is absent on managed intake responses — Cardinal Gray selects the filing path during fulfillment.

Available options:

MANAGED

confirmationImg

string<uri>

Presigned URL to a PNG confirmation screenshot captured from the state portal. ONLINE_PORTAL only.

applicationNumber

string

Application/tracking number returned by the state portal, when available.

packetUrl

string<uri>

Presigned URL to the generated mail packet PDF. MAIL only.

packetS3Key

string

S3 key for the mail packet PDF. MAIL only.

checkAmount

number

Dollar amount to write on the enclosed check. MAIL only.

checkPayee

string

Payee for the enclosed check. MAIL only.

Sign Title Documents Get Submission

⌘I

Title Entries

Title Actions

Submission

Managed submission mode

Attachments

Scenario key

Response codes

Authorizations

Path Parameters

Body

Response

​Managed submission mode

​Attachments

​Scenario key

​Response codes

Authorizations

Path Parameters

Body

Response

Managed submission mode

Attachments

Scenario key

Response codes