Modernizing the USPS Web Tools Developer Experience

USPS Web Tools APIs were outdated—PDF-only documentation, non-standard authentication, XML everywhere. We built open-source tools to fix that developer experience. Here's how.

The U.S. Postal Service opened up its data through a free USPS Web Tools® account. The API set covered everything from address verification to tracking and shipping labels. Unfortunately, many of those endpoints were developed over a decade ago—XML-only, PDF documentation, no interactive tools—while developer expectations moved toward JSON, OAuth, and live API explorers.

Important update: USPS retired the Web Tools platform on January 25, 2026. See the official USPS retirement notice and the new USPS Developer Portal. We're leaving this post up as a retrospective because the lessons still apply to anyone improving a legacy API experience.

We saw ways to improve the experience. Now, we can't change the APIs themselves, but an open-source project using new tools could make a difference. API documentation often ranks number one for how developers evaluate a technology. The USPS Web Tools reference docs? Only available as PDFs. We decided to start there.

TL;DR

Note: USPS Web Tools was retired on January 25, 2026. If you're looking for the current platform, start with the USPS Developer Portal. The summary below covers Lob's work on the legacy Web Tools platform.

We crafted a USPS Web Tools OpenAPI 3.0 specification from the PDF docs, then used the spec to generate modern USPS Web Tools API documentation with Redoc and host them on Netlify. Many companies offer an interactive API explorer as part of their documentation, we thought a good solution was a USPS Web Tools public workspace with Postman. Finally, we created a video tutorial so you can try out these tools.

Let's look at the challenges we faced improving the developer experience.

Reverse engineering an OpenAPI specification

Turning existing API docs into an OpenAPI specification should be straightforward. It rarely is. APIs drift from standards over time—non-standard auth, shared paths, undocumented response structures—and those quirks don't map cleanly to a spec. We achieved a valid specification, but the spec design required creative compromises to accommodate the U.S. Postal Service API.

Problem #1: non-standard API authentication

Non-standard authentication hit us first.

OpenAPI supports standard auth types—basic, bearer, API key, OAuth 2, OpenID Connect. USPS didn't use any of them. Instead, USPS embedded a USERID attribute in the XML query param's parent node. The newer USPS APIs now use OAuth 2.0 Client Credentials, which fixes this.

For example: <AddressValidateRequest USERID="{WEB\_TOOLS\_USERNAME}">

Solution: omit the security scheme

We omitted the security scheme from our specification and used the Redoc option noAutoAuth=true. That option removes the auto-inserted authentication link from each endpoint. We still needed to explain how USPS Web Tools authentication works. We added a description of authentication using tags in OpenAPI and set x-traitTag to true. Redoc inserts a new section without an associated endpoint—exactly what we needed.

Problem #2: all endpoints share the same path

OpenAPI requires unique paths, but all USPS endpoints share /ShippingAPI.dll and define their function via the API query param.

Solution: append the API parameter to each path

We used a hacky workaround: define a parameter named API AND append it to the path, making each path unique.

/ShippingAPI.dll?API=Verify:  get:    summary: 'Verify a US address'    operationId: verify    tags:      - Address    parameters:      - name: API        in: query        description: This query parameter defines the resource you are accessing        required: true        schema:          type: string          default: Verify

Problem #3: complex, undocumented response objects

Response objects gave us the most trouble—they were large, complex, and poorly documented. USPS documentation didn't show how responses changed based on address type, error state, or optional fields. It was hard to tell how child objects were organized and whether they were returned as arrays. We documented what we could confirm. We replicated conditions to capture example responses and confirm object structures.

Solution: open it up to the community

We hoped USPS employees and the developer community would file issues or make pull requests to improve the spec and docs. The bigger idea still stands: open-source specs let the community catch errors, add examples, and fill documentation gaps faster than any single team could.

Building documentation with Redoc

Redoc is an open-source tool for generating documentation from OpenAPI (fka Swagger) definitions. There's a paid service called Redocly with more features, but for this project we used the open-source redoc-cli tool.

Problem #4: XML examples don't render in Redoc

Including an example for the XML parameter created another challenge. XML can be complex, and seeing a real example beats reading a description. In Redoc, simple type parameters support examples, but object type examples don't display.

Solution: embed examples directly in the description field

To work around this, we added examples in the description wrapped in a styled div with non-breaking whitespace for indentation. It's a hack, but it works—see the results.

USPS public workspace with Postman

If you've used Postman public workspaces, you'll recognize the setup—Lob launched one last summer. You can fork our address validation, domestic mail service, and track & confirm collections to test requests immediately. You can still fork the collection and environment in the USPS Postman public workspace to see the request structure, variables, and pre-request scripts.

The underlying APIs may no longer return live responses. The collections still show you how to structure requests, set variables, and build the workflow.

Problem #5: editing XML in a single-line text input

The XML parameter is the one thing you'll modify when exploring these APIs, but editing nested XML in a single-line text input is error-prone and hard to read.

Solution: set XML variables with a pre-request script

The pre-request script tab in Postman lets you build XML from variables instead of editing raw strings. You define all the values as variables at the top of the script. You change a variable like address1 or city, and the script builds the full XML param when you send the request.

Conclusion

The project documented real solutions to legacy API problems that still apply today. The problems were real, and USPS has since launched a modern Developer Portal with OAuth 2.0, RESTful endpoints, and interactive docs. If you're building against USPS APIs today, start at developers.usps.com. For the legacy workflow and code patterns, watch our video tutorial: How to use the USPS Web Tools API with Javascript and Node. The video covers Axios, XMLBuilder2, and XML-to-JSON transformation—patterns that work beyond USPS.

Improving a developer experience usually means working around constraints the original designers didn't anticipate. You'll face tradeoffs between spec compliance and practical usability. We say bend the rules. You'll ship something developers can actually use.