Address Verification API - Developer Guide

1. Overview & Introduction

The Address Verification API validates and standardizes a submitted address against authoritative postal and geographic data, returning a corrected and standardized representation. Use it when you need to confirm that an address is deliverable and to normalize it into a consistent form before storing it, routing it, or using it downstream.

The domain model is small. The core input is an Address — a loosely structured, user-supplied set of address components (street lines, city, state, ZIP). The core output of validation is a standardized address result, which pairs a corrected/normalized address with a list of corrections describing what the service changed and a message indicating whether the outcome was an error or a warning. A related capability, ZIP decoding, takes a ZIP code and returns the geographic values (city, county, state, county FIPS) associated with it. Both operations return enriched geographic references (state and county) as lookup values carrying a code and a human-readable description.

The API is served across three environments, expressed in the spec's server definition via an env variable: a production environment, a staging environment, and a test environment. Conceptually, use the test environment for integration development, staging for pre-production verification, and production for live traffic. Refer to the spec's servers block for the exact host pattern and permitted environment values.

All operations require OAuth 2.0 authorization (see Authentication). Addresses submitted for validation may contain personally identifiable location data; treat request and response payloads as sensitive and avoid logging them in plain text. There are no fields in the schema that mark data as regulated, so handle all address data according to your own organization's data-handling standards.

2. Getting Started / First Call

Prerequisites

• A Vitu-issued OAuth 2.0 client credential (client ID and secret).
• The ability to make server-to-server HTTPS requests.
• Familiarity with the OAuth 2.0 client-credentials grant.

Obtain access

Credentials are issued by Vitu and can be obtained from the Key Management area within Vitu's Developer Portal.

Minimal happy path

1. Get a token. Exchange your client credentials for an access token using the client-credentials grant (see the oneVituOauth scheme in the spec for the token endpoint and scope).
2. Call the address-validation operation (validateAddressUsingPUT), supplying an address in the request body per the Address schema.
3. Read the result. Inspect the returned standardized address, the corrections list, and the error/warning message to determine what changed and whether the input was accepted. See the AddressValidationResultDTO schema for the exact shape.

A first successful call requires only step 1 plus step 2 — validation has no resource prerequisites beyond a valid token.

3. Authentication & Access Walkthrough

All operations are protected by a single OAuth 2.0 scheme, oneVituOauth, using the client-credentials grant with the oneapi:access scope. The spec's securitySchemes block is the formal definition (grant type, token URL, scope). This section covers only the operational mechanics.

Obtaining credentials. Client credentials are issued by Vitu and retrieved from the Key Management area of Vitu's Developer Portal.

Obtaining a token. Perform a client-credentials token request against the token endpoint defined in the spec, requesting the oneapi:access scope. The response contains a bearer access token.

Attaching the token. Send the access token as a bearer token in the Authorization header on every request.

Token lifecycle.

• Access tokens expire. Cache and reuse a token until shortly before its expiry, then request a new one. (The token response conveys the lifetime; the spec does not fix a value.)
• The client-credentials grant does not issue refresh tokens — to "refresh," simply request a new token with your credentials.
• On a 401 response, obtain a fresh token and retry once. If a 403 persists, the credential lacks the required scope or access — this is not resolved by retrying.

Single scheme. Only one security scheme exists. There is no API-key or user-delegated (authorization-code) alternative; do not attempt one.

4. Key Concepts & Glossary

Relationships. The two operations are independent — neither requires the other. Both draw on the same geographic reference data, so the state/county lookup values returned by validation and by ZIP decode are of the same type. There is no parent/child resource hierarchy and no persisted resource lifecycle: both operations are stateless request/response computations.

5. Common Use Cases & Integration Patterns

All operations here are synchronous request/response calls. There are no async jobs, callbacks, or resources to poll.

Use case A - Validate and standardize an address before storing it

Intent: normalize user-entered address data to a canonical form.

1. Obtain a token (once, cached).
2. Call validateAddressUsingPUT with the raw address.
3. Inspect the result:

• Read the error/warning flag to decide whether to accept the outcome.
• Read the corrections list to detect what was changed — this drives whether you prompt the user to confirm a correction.
• Persist the standardized address from the result, not the original input.

Pattern: validate at the point of capture. Because correction categories tell you what changed but not the original values, capture both the submitted and standardized forms if you need an audit trail.

Use case B - Resolve a ZIP code to its geography

Intent: derive city/county/state for a known ZIP, e.g., to prefill a form or attach FIPS data.

1. Obtain a token.
2. Call decodeZipUsingGET with the ZIP.
3. The result is a list — a single ZIP may map to multiple geographic rows. Handle more than one result and use pagination if the set is large (see Pagination).

Pattern: treat the response as a set, not a single record. Choose or disambiguate among returned rows in your own logic.

6. Behavioral & Operational Notes

• Validation is a computation, not a resource write. No entity is created or persisted by validating an address; the response is derived data. (The spec lists a 201 Created response on the validation operation — see the flag below.)
• Judge success by the result body, not the status code. A 200 can still carry an error message. Always evaluate the error/warning flag in the result before treating an address as validated.
• Corrections describe categories, not diffs. The result tells you a category of change occurred; it does not return the pre-correction values. Retain your original input if you need to show a before/after.
• ZIP decode returns a collection. Expect zero, one, or many rows for a ZIP.

7. Rate Limiting & Quotas

Both operations can return a "too many requests" response (TooManyRequests in the spec) when a rate limit is exceeded. The spec does not publish specific limits or a machine-readable retry header; the response body carries a message. On this response, back off and retry after a delay (see the agent failure-handling rules for a backoff convention).

8. Pagination Conventions

The ZIP-decode operation supports offset-based pagination via the shared limit and offset parameters (defined once in the spec as reusable parameters). Use limit to cap page size and offset to advance through pages. The validation operation is not paginated. Refer to the spec for the parameters' bounds and defaults rather than hard-coding them.

9. Error Handling & Troubleshooting

Handle failures by class, not by individual code. Reference the spec for the exact status codes and the TooManyRequests response schema.

10. Support & Resources

​For any API assistance, contact Vitu's API support team at [email protected].