Case Study 2: Federal Benefits' API Modernization for Inter-Agency Data Sharing

Background

The Federal Benefits Administration (FBA) manages retirement, disability, and survivor benefit programs for 4.8 million federal employees and retirees. Their mainframe — a z16 running z/OS 3.1 — processes benefit calculations, eligibility determinations, payment disbursements, and enrollment changes. The core COBOL application suite, known internally as "BENEFIX," has been in continuous operation since 1986 and comprises over 6 million lines of COBOL across 1,200 programs.

Sandra Washington, the CTO, and Marcus Chen, the lead systems architect, faced a mandate from the Office of Management and Budget (OMB): all federal agencies must provide standardized APIs for inter-agency data sharing by fiscal year 2026. The directive was clear — no more point-to-point file transfers, no more manual data calls, no more faxed requests. APIs or nothing.

The Challenge: Regulatory Complexity Meets Technical Debt

The FBA shared data with 23 other federal agencies. Each sharing arrangement had its own:

• Legal authority — A specific section of federal law authorizing the data exchange
• Data sharing agreement (DSA) — A formal document specifying what data could be shared, with whom, for what purpose, and under what restrictions
• Technical implementation — Ranging from encrypted FTP drops to SFTP batch transfers to (in two cases) literally mailing encrypted USB drives

Every integration was unique. The Social Security Administration got a weekly extract of retirement benefit amounts. The Department of Veterans Affairs got a monthly extract of dual-eligibility flags. The Office of Personnel Management got a daily extract of enrollment changes. Each extract was a custom batch job, a custom copybook, and a custom file format.

When Sandra calculated the maintenance cost, the numbers were alarming: 23 integrations × an average of 40 hours/year maintenance each = 920 hours/year just keeping file transfers running. Plus 14 incident tickets per month for failed transfers, encoding issues, and format mismatches.

The Privacy Constraint

Federal benefits data is among the most sensitive government data. The Privacy Act of 1974, the Computer Matching and Privacy Protection Act, and agency-specific regulations impose strict requirements:

• Minimum necessary: Share only the data fields required for the receiving agency's authorized purpose
• Audit trail: Every data access must be logged with who accessed what, when, and why
• Purpose limitation: Data received for one purpose cannot be used for another
• Individual notice: In some cases, beneficiaries must be notified that their data was shared

These requirements meant that a single "benefits API" wouldn't work. Each consuming agency needed a tailored view of the data, exposing only the fields their DSA authorized.

The Architecture

Marcus designed a three-tier API architecture that met both the OMB mandate and the privacy requirements:

Tier 1: Internal Service Layer (z/OS Connect)

z/OS Connect EE exposed the core BENEFIX programs as internal services. These services returned the full data set — all fields for a given beneficiary or benefit record. They were not directly accessible from outside the mainframe network.

Key services: - beneficiary-inquiry — Full beneficiary demographics and enrollment - benefit-calculation — Current benefit amounts and calculation details - payment-history — Payment records for a specified date range - eligibility-check — Real-time eligibility determination - enrollment-status — Current enrollment and plan selections

Each service mapped to an existing CICS transaction. Marcus's team created service archives for each, following the same pattern SecureFirst used — import the copybook, map the fields, deploy the .sar.

Tier 2: Agency-Specific API Layer (API Gateway)

The API gateway — deployed using IBM API Connect — hosted agency-specific API definitions. Each agency's API was a filtered, transformed view of the internal services.

For example, the Social Security Administration's API:

# SSA API — authorized by 5 USC 8347 and DSA-FBA-SSA-2024
paths:
  /api/v1/ssa/beneficiaries/{ssn}/retirement-benefit:
    get:
      summary: "Retrieve retirement benefit amount for dual-eligibility determination"
      parameters:
        - name: ssn
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{9}$'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  beneficiaryId:
                    type: string
                  monthlyBenefitAmount:
                    type: string
                    description: "Monthly gross benefit in USD"
                  benefitEffectiveDate:
                    type: string
                    format: date
                  retirementType:
                    type: string
                    enum: [VOLUNTARY, DISABILITY, DEFERRED]
                  # Note: NO demographic fields, NO payment history,
                  # NO enrollment details — SSA's DSA doesn't authorize them

The VA's API returned different fields:

# VA API — authorized by 38 USC 5106 and DSA-FBA-VA-2023
paths:
  /api/v1/va/beneficiaries/{ssn}/eligibility:
    get:
      summary: "Check dual-eligibility for VA benefit coordination"
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  beneficiaryId:
                    type: string
                  isFederalRetiree:
                    type: boolean
                  federalServiceYears:
                    type: integer
                  hasDisabilityBenefit:
                    type: boolean
                  disabilityPercentage:
                    type: integer
                    minimum: 0
                    maximum: 100
                  # Different fields than SSA — only what VA's DSA authorizes

The gateway enforced the filtering. Even if the internal service returned 50 fields, the agency-specific API only exposed the 5-8 fields that agency was authorized to receive. This was implemented as response transformation policies in API Connect — the gateway stripped unauthorized fields before the response left the network.

Tier 3: Security and Audit Layer

Every API call passed through a security and audit layer that enforced:

Authentication: Mutual TLS with agency-specific client certificates. Each agency had a unique certificate issued by the FBA's certificate authority. No API keys, no basic auth, no OAuth for inter-agency calls — mTLS was mandatory per federal security standards (NIST SP 800-53).

Authorization: After mTLS authentication, the gateway verified that the calling agency's certificate mapped to an authorized consumer profile, and that the profile was authorized for the specific API path being called. SSA's certificate couldn't access the VA's API, and vice versa.

Audit logging: Every API call generated an audit record containing: - Calling agency identifier (from certificate DN) - API path and operation - Beneficiary identifier (SSN or beneficiary ID) being accessed - Timestamp - Response status code - Data fields returned (list of field names, not values)

These audit records were written to a dedicated DB2 table and retained for 7 years per federal records management requirements. Sandra's team built a quarterly audit report that showed each agency's data access patterns, flagged anomalous requests, and verified compliance with DSA terms.

Rate limiting: Agency-specific rate limits based on their expected query volume:

Implementation Timeline

Phase 1: Pilot (Months 1-6)

Marcus selected three agencies for the pilot: SSA, VA, and OPM. These were the highest-volume consumers and had the most technically sophisticated teams.

Month 1-2: Infrastructure. - z/OS Connect EE deployed on both production LPARs - API Connect deployed in the FBA's secure cloud enclave (FedRAMP High) - mTLS infrastructure: FBA certificate authority established, pilot agency certificates issued - Network paths: dedicated VPN tunnels to each pilot agency's network

Month 3-4: API development. - Five internal services built on z/OS Connect (the services listed in Tier 1) - Three agency-specific APIs designed, reviewed, and approved by each agency's technical team and privacy officer - Response transformation policies implemented in API Connect - Audit logging framework deployed

Month 5-6: Testing and certification. - Integration testing with each agency using sandbox data - Security assessment by the FBA's Information Security team - Privacy impact assessment by the FBA's Chief Privacy Officer - Authority to Operate (ATO) granted for the API platform

Phase 2: Migration (Months 7-14)

With the pilot proven, Sandra's team began migrating the remaining 20 agencies. They established a repeatable onboarding process:

1. DSA review (2 weeks) — Confirm the existing DSA covers API-based data sharing. If not, initiate a DSA amendment (this added 3-6 months for some agencies).
2. API design (1 week) — Map DSA-authorized fields to an agency-specific API. Review with the agency's technical and privacy teams.
3. Certificate provisioning (1 week) — Issue mTLS certificates and establish network connectivity.
4. Implementation (2 weeks) — Configure the API gateway, deploy transformation policies, set rate limits.
5. Testing (2 weeks) — Integration testing in sandbox, then supervised production testing.
6. Go-live (1 day) — Enable production access with monitoring.
7. Parallel running (4 weeks) — Run both the old file transfer and the new API in parallel. Compare results daily. Decommission the file transfer when results match for 30 consecutive days.

The parallel running period was Sandra's non-negotiable requirement. "We're not turning off a working integration until we've proven the replacement works identically," she said. Marcus initially pushed back — parallel running doubled the work — but after the first migration caught a data mapping error that would have sent incorrect benefit amounts to the Department of Labor, he never argued again.

Phase 3: Optimization (Months 15-18)

With all 23 agencies migrated, the team focused on optimization:

Caching. Some data rarely changes. A beneficiary's retirement type doesn't change after it's set. The API gateway was configured to cache stable data fields with a 24-hour TTL, reducing mainframe hits by 35%.

Bulk query API. Several agencies needed to look up hundreds or thousands of beneficiaries in a single batch. Instead of making individual API calls, Marcus added a bulk query endpoint: POST /api/v1/{agency}/beneficiaries/bulk accepting up to 1,000 SSNs per request. The backend used a CICS channel with containers to process the batch efficiently.

Asynchronous large queries. GAO auditors occasionally needed data on all 4.8 million beneficiaries. An API returning 4.8 million records synchronously was impractical. Marcus implemented an async pattern: GAO submits a query, receives a job ID, and polls for status. When the query completes, GAO retrieves the result from a secure file drop — but the query initiation, status checking, and result notification are all API-driven.

Technical Challenges

Challenge 1: The COBOL Date Problem

BENEFIX stored dates in multiple formats across different programs: PIC 9(8) for YYYYMMDD, PIC 9(6) for YYMMDD, PIC 9(7) for YYYYDDD (Julian date), and even PIC X(10) for MM/DD/YYYY in some display-oriented programs.

The API needed to present dates consistently. Marcus defined a standard: all API date fields use ISO 8601 (YYYY-MM-DD). z/OS Connect service archives included date transformation rules that converted each COBOL date format to ISO 8601 on the way out and back on the way in.

The tricky part was the Julian dates. PIC 9(7) value 2025076 means the 76th day of 2025 (March 17). The transformation had to account for leap years. Marcus wrote a reusable z/OS Connect interceptor for Julian date conversion rather than repeating the logic in every service archive.

Challenge 2: The Audit Volume Problem

With 23 agencies making an aggregate 300,000+ API calls per day, the audit logging table grew by 9 million rows per month. DB2 performance for the quarterly audit reports degraded to the point where reports took 6 hours to run.

Solution: Partitioned the audit table by month. Implemented a rolling archive that moved records older than 12 months to a compressed archive table. Quarterly reports ran against the active partition only, completing in 20 minutes. The 7-year retention requirement was met by the archive table, which was backed up to tape monthly.

Challenge 3: The Agency That Couldn't Do mTLS

The Government Accountability Office (GAO) had an older infrastructure that couldn't support mutual TLS. Their systems could validate the server's certificate but couldn't present a client certificate. Refusing GAO access wasn't an option — they have statutory audit authority.

Solution: For GAO only, Marcus implemented an alternative authentication flow: IP whitelist + OAuth 2.0 client credentials + enhanced audit logging. GAO's requests were restricted to their registered IP range, authenticated with OAuth tokens, and subjected to additional logging that captured request headers and network metadata. This was documented as a risk-accepted deviation from the mTLS standard, approved by the CISO.

Challenge 4: The DSA Amendment Bottleneck

Seven agencies needed DSA amendments before they could switch to API-based data sharing. Their existing DSAs specified "electronic file transfer" as the sharing method, and the legal teams interpreted "API" as a different method requiring a formal amendment.

Sandra escalated to the OMB, which issued a clarification that APIs were an acceptable implementation of electronic data sharing under existing DSAs. This unblocked five of the seven agencies. The remaining two had DSA language so specific that amendments were genuinely required — those took an additional 5 months.

Lesson learned: When planning API modernization in a government context, review all data sharing agreements for language that may constrain the technical implementation. Start the legal review process in parallel with technical implementation, not after.

Challenge 5: The Beneficiary Who Was in Two Systems

During parallel running for the Department of Labor integration, the team discovered that the API returned a different benefit amount than the file extract for 347 beneficiaries. Investigation revealed that the file extract job ran at 2 AM and captured the benefit amount after a batch adjustment. The API called the CICS transaction, which read the pre-adjustment amount from VSAM. The batch adjustment updated VSAM, but the CICS region's file buffers still held the old value until the next file close/reopen cycle.

Solution: Added a EXEC CICS SET FILE(...) CLOSED / EXEC CICS SET FILE(...) OPEN sequence to the batch adjustment job's completion step, forcing CICS to refresh its buffers. Also documented in the API specification that benefit amounts reflect the current value at time of inquiry, which may differ from batch-calculated values during overnight processing windows.

Results

After 18 months:

The automated audit trail was the unexpected hero. When an Inspector General inquiry asked "which agencies accessed beneficiary X's data in Q3?", Marcus could answer in minutes with a SQL query against the audit table. Previously, this required correlating FTP logs, batch job records, and file delivery receipts — a process that took days and was never complete.

Sandra's Reflection

"The technology was the easy part," Sandra told a government IT conference. "The hard parts were the DSA amendments, the inter-agency coordination, and convincing 23 agency technical teams to change how they'd been doing things for 15 years. Marcus could build an API in a week. Getting the legal authority to use it took months.

"But the result is worth it. We went from 23 fragile, bespoke file transfers to 23 standardized, secured, audited APIs. Our privacy officer can see exactly what data is being shared with whom, in real time. Our auditors can verify compliance in minutes, not weeks. And when the next agency needs our data, we can onboard them in weeks, not months.

"The mainframe is still the system of record. The COBOL programs still run the benefit calculations. What changed is that those programs are now accessible to any authorized consumer, through a standard interface, with full security and audit. That's what modernization actually looks like."

Discussion Questions

1. The FBA chose agency-specific APIs with field-level filtering rather than a single comprehensive API with authorization-based field visibility. What are the pros and cons of each approach? Which is more maintainable at scale?

2. The parallel running period caught a data consistency issue (Challenge 5) that would have been a serious problem in production. Should parallel running be mandatory for all API migrations, or only for high-risk integrations?

3. The GAO mTLS exception was a pragmatic compromise. How do you balance security standards with operational reality? What additional compensating controls would you recommend?

4. The DSA amendment bottleneck delayed 7 of 23 agency migrations. How should technical teams engage with legal and compliance teams earlier in the modernization process?

5. The audit logging generated 9 million rows per month. As API adoption grows, this will increase. Design a long-term audit data management strategy that meets the 7-year retention requirement without degrading query performance.

6. Sandra said "the technology was the easy part." Based on your experience, do you agree? What non-technical factors most often determine the success or failure of mainframe API modernization projects?