AI Agent Reference

Valid OAuth token (scope oneapi:access)   [required for ALL operations]
 ├─ GetCustomerLookup            requires: locationId, state, searchBy
 ├─ CreateTransaction            requires: VAEVRTransactionDTO (+ optional callbackUrl, refNumber)
 │    └─ produces: transactionId, refNumber, fees, forms, callbacks
 ├─ UpdateTransaction            requires: existing transaction (id or refNumber), not terminal
 ├─ CancelTransaction            requires: existing transaction (id or refNumber), not terminal
 ├─ GetTransactionFees           requires: existing transaction + processing advanced enough to compute fees
 ├─ GetTransactionForms          requires: existing transaction + documents generated
 ├─ DownloadTransactionForms     requires: forms exist
 ├─ DownloadTransactionDocument  requires: known documentId (from GetTransactionForms)
 └─ GetTransactionIdByRefNumber  requires: a refNumber previously supplied/received

OP: GetCustomerLookup
AUTH: oneapi:access (REQUIRED)
PRECONDITIONS: locationId, state, searchBy present (REQUIRED); identity fields per searchBy mode (OPTIONAL per mode)
SIDE_EFFECTS: none (query only)
SUCCESS_SIGNAL: 200 with CustomerLookupResponseDTO.customers populated (REQUIRED)
AGENT_NOTE: handles PII (DL/SSN/FEIN); do not log payload.

OP: CreateTransaction
AUTH: oneapi:access (REQUIRED)
PRECONDITIONS: valid VAEVRTransactionDTO body (REQUIRED); callbackUrl (OPTIONAL); refNumber (OPTIONAL, recommended for correlation); transactionType (OPTIONAL)
SIDE_EFFECTS: creates a transaction; enqueues async processing; may trigger downstream DMV submission depending on ServiceType
SUCCESS_SIGNAL: 202 = accepted, NOT complete. Terminal outcome = callback status field (TransactionStatusEnum/UniversalStatusEnum) or discriminated CallbackDTO (REQUIRED to confirm)

OP: UpdateTransaction
AUTH: oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction (id or refNumber) (REQUIRED); not in terminal state (REQUIRED); valid body (REQUIRED)
SIDE_EFFECTS: mutates the transaction; re-enqueues async processing
SUCCESS_SIGNAL: 202 accepted; confirm via callback/status (REQUIRED)

OP: CancelTransaction
AUTH: oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction (id or refNumber) (REQUIRED); not terminal (REQUIRED); message (OPTIONAL)
SIDE_EFFECTS: requests cancellation; state change is async and may be irreversible once terminal
SUCCESS_SIGNAL: 202 accepted; confirm terminal cancelled state via callback/status (REQUIRED)

OP: GetTransactionFees
AUTH: oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction (REQUIRED); fees computed (may be empty if processing not advanced)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: 200 with FeeDTO array (REQUIRED)

OP: GetTransactionForms
AUTH: oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction (REQUIRED); documents generated (may be empty if not yet produced)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: 200 with FormDocumentDTO array (REQUIRED)

OP: DownloadTransactionForms
AUTH: oneapi:access (REQUIRED)
PRECONDITIONS: forms exist (REQUIRED); target filter (OPTIONAL, DocumentTarget)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: 200 application/pdf binary (REQUIRED)

OP: DownloadTransactionDocument
AUTH: oneapi:access (REQUIRED)
PRECONDITIONS: documentId known from GetTransactionForms (REQUIRED); blank flag (OPTIONAL)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: 200 application/pdf binary (REQUIRED)

OP: GetTransactionIdByRefNumber
AUTH: oneapi:access (REQUIRED)
PRECONDITIONS: refNumber (UUID) previously issued (REQUIRED)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: 200 with integer transactionId (REQUIRED)

ON_FAILURE_AUTH  (401)
MEANING: token missing/expired/invalid
RETRY: yes, once, after obtaining fresh token
BACKOFF: none (single re-auth)
STOP: second consecutive 401 → treat as credential/scope defect; do not loop

ON_FAILURE_FORBIDDEN  (403)
MEANING: authenticated but not authorized
RETRY: no
STOP: immediately; escalate for access provisioning

ON_FAILURE_VALIDATION  (400, Errors schema)
MEANING: malformed request / invalid field values
RETRY: no (not without changing payload)
STOP: immediately; parse Errors, correct fields, resubmit as new attempt

ON_FAILURE_NOT_FOUND  (404)
MEANING: referenced transaction/resource does not exist
RETRY: no
STOP: verify identifier; try GetTransactionIdByRefNumber if only refNumber held

ON_FAILURE_RATE_LIMIT  (429)
MEANING: throttled
RETRY: yes
BACKOFF: honor Retry-After first; else exponential backoff + jitter
STOP: after capped attempts; surface throttle failure

ON_FAILURE_SERVER  (500, Errors schema)
MEANING: server-side failure
RETRY: yes for idempotent reads; CAUTION for submissions (idempotency undefined)
BACKOFF: exponential + jitter
STOP: after capped attempts; for submissions, reconcile state before any re-submit

RECIPE: File title & registration (full service)

1. [auth] acquire token (oneapi:access)
2. (optional) GetCustomerLookup  -> pre-fill owner data
3. CreateTransaction (body=VAEVRTransactionDTO, set refNumber, set callbackUrl) -> expect 202
4. WAIT for callback (match on refNumber; branch on callbackType)
   - - OR poll GetTransactionFees / GetTransactionForms until populated
5. GetTransactionFees        -> read fees
6. GetTransactionForms       -> enumerate documents
7. DownloadTransactionForms  OR  DownloadTransactionDocument(documentId) -> retrieve PDFs

RECIPE: Forms-and-fees only

1. [auth]
2. CreateTransaction (ServiceType=FormsAndFees, set refNumber) -> 202
3. WAIT/poll until fees+forms available
4. GetTransactionFees ; GetTransactionForms ; download as needed

RECIPE: Amend an in-flight transaction

1. [auth]
2. (if only refNumber) GetTransactionIdByRefNumber -> transactionId
3. UpdateTransaction (id or refNumber, revised body) -> 202
4. Confirm via callback/status; do not assume immediate effect

RECIPE: Cancel a transaction

1. [auth]
2. CancelTransaction (id or refNumber, optional message) -> 202
3. Confirm terminal cancelled state via callback/status before treating as cancelled

RECIPE: Correlate an inbound callback

1. Receive POST at callbackUrl
2. (if HMAC configured) verify HMAC/SHA-256 signature -> reject if invalid
3. Match refNumber to local record
4. Branch on callbackType (SUCCESS|FAILURE|DMVDESK|EVR|INVOICED)
5. Read type-specific status/fields; return 200 to acknowledge