Address Verification — AI Agent Reference | Vitu Production Developer Portal

AI Agent Reference

Compact reasoning layer for automated agents. The agent reads params, schemas, types, and status codes directly from the OpenAPI spec; this section supplies only intent, ordering, safety, and failure logic.

Operation intent

operation_id	Goal
`validateAddressUsingPUT`	Validate and standardize a submitted address; return corrected form + correction categories + error/warning flag.
`decodeZipUsingGET`	Resolve a ZIP code to its associated geographic values (city, county, county FIPS, state) as a list.

Prerequisite / dependency tree

Valid OAuth token (oneVituOauth, scope oneapi:access)
- validateAddressUsingPUT   (no resource prerequisites)
- decodeZipUsingGET         (no resource prerequisites)

No operation depends on another. No persisted resources exist.

Per-operation reasoning contracts

OPERATION: validateAddressUsingPUT
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — valid bearer token
                  OPTIONAL — address body fields (none marked required in schema)
  SIDE_EFFECTS:   None (stateless computation; no resource persisted)
  SUCCESS_SIGNAL: REQUIRED — response received AND result's error/warning
                  boolean indicates non-error. Inspect corrections list to
                  detect applied changes. Do NOT rely on HTTP status alone.
  AGENT_NOTE:     A 200 may still carry an error message; the error/warning
                  flag is the authoritative success signal.

OPERATION: decodeZipUsingGET
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — valid bearer token; zip path value
                  OPTIONAL — application query value; limit/offset paging
  SIDE_EFFECTS:   None (read-only lookup)
  SUCCESS_SIGNAL: REQUIRED — 2xx with an array body (may be empty, one, or many)
  AGENT_NOTE:     Treat result as a set; a single ZIP may yield multiple rows.
                  Use limit/offset to page; refer to spec for bounds/defaults.

Safety classification

operation_id	Classification
`validateAddressUsingPUT`	Safe (no persistence; despite PUT verb, no resource is mutated)
`decodeZipUsingGET`	Safe (read-only)

AGENT_NOTE: validateAddressUsingPUT uses the PUT method but performs no state change per the domain model. Do not treat it as mutating.

Failure-handling rules

ON_FAILURE_AUTH_UNAUTHORIZED:
  MEANS:   token missing/expired/invalid
  RETRY:   yes — obtain fresh token, retry once
  BACKOFF: none
  STOP:    if failure persists after one fresh-token retry

ON_FAILURE_AUTH_FORBIDDEN:
  MEANS:   token valid but lacks required access/scope
  RETRY:   no
  STOP:    immediately; escalate credential/scope issue

ON_FAILURE_NOT_FOUND:
  MEANS:   target not resolvable (e.g., unknown zip)
  RETRY:   no
  STOP:    immediately; treat as valid empty/negative result

ON_FAILURE_RATE_LIMIT:
  MEANS:   TooManyRequests response returned
  RETRY:   yes
  BACKOFF: exponential + jitter
  STOP:    after bounded attempt ceiling

ON_FAILURE_SERVER:
  MEANS:   transient server-side error
  RETRY:   yes
  BACKOFF: exponential + jitter
  STOP:    after bounded attempt ceiling

ON_FAILURE_VALIDATION_OUTCOME:
  MEANS:   request succeeded but result error flag is set
  RETRY:   no (not an HTTP failure)
  STOP:    surface message; correct input before re-submitting

Workflow recipes

RECIPE: Standardize an address

1. Ensure valid token (oneapi:access).
2. validateAddressUsingPUT(address).
3. Check result error/warning flag → if error, apply ON_FAILURE_VALIDATION_OUTCOME.
4. Read corrections list → note applied change categories.
5. Use standardized address from result (not the input).

RECIPE: Resolve ZIP geography

1. Ensure valid token (oneapi:access).
2. decodeZipUsingGET(zip [, limit, offset]).
3. Iterate result set; if paginated, advance offset until fewer than limit rows returned.
4. Disambiguate among rows in caller logic.