> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cardinalgray.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Submission
> Fetch a submission's current status, application number, and confirmation screenshot
Use this endpoint to poll the state of a queued `ONLINE_PORTAL` submission and retrieve the portal `applicationNumber` and confirmation screenshot once available. Managed-mode organizations use it to track their intake request: the response includes `intakeMode: "MANAGED"`, and `method` is absent until Cardinal Gray selects the filing path.
## Status values
Poll until `status` reaches one of the terminal states.
| Status | Meaning |
| -------------------- | --------------------------------------------------------------------------------------- |
| `AWAITING_READINESS` | Managed intake recorded — Cardinal Gray's title operations team is preparing the filing |
| `PENDING` | Queued, worker has not started |
| `SUBMITTED` | Worker submitted to the state, awaiting acknowledgement |
| `UNDER_REVIEW` | State/portal has acknowledged and is reviewing |
| `ACTION_REQUIRED` | State needs follow-up documents — see `feedbackMessage` |
| `ACCEPTED` | State accepted the submission |
| `REJECTED` | State rejected the submission — see `error` and `feedbackMessage` |
| `CANCELED` | Cardinal Gray or the user canceled before completion |
| `ERROR` | Unrecoverable error running the worker — see `error` |
When available, `confirmationImg` is a presigned URL to a PNG screenshot captured from the state portal.
```bash theme={null}
curl -X GET "https://api.cardinalgray.com/title/123e4567-e89b-12d3-a456-426614174000/submit/b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```json 200 Under review theme={null}
{
"submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
"status": "UNDER_REVIEW",
"method": "ONLINE_PORTAL",
"applicationNumber": "KS-2026-000123",
"confirmationImg": "https://s3.amazonaws.com/...&X-Amz-Signature=..."
}
```
```json 200 Managed intake awaiting readiness theme={null}
{
"submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
"status": "AWAITING_READINESS",
"intakeMode": "MANAGED"
}
```
```json 200 Accepted theme={null}
{
"submissionId": "b8f3c1a2-8a4e-4a8b-9b2f-6e5c1b1a0f11",
"status": "ACCEPTED",
"method": "ONLINE_PORTAL",
"applicationNumber": "KS-2026-000123",
"confirmationImg": "https://s3.amazonaws.com/...&X-Amz-Signature=..."
}
```
## OpenAPI
````yaml GET /title/{id}/submit/{submissionId}
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/{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:
parameters:
id:
name: id
in: path
required: true
schema:
type: string
description: Unique identifier of the title entry
schemas:
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 — 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 — 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 — 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
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 — 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.
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.
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
responses:
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
````