Social Security Administration (SSA) Statement XML Developer Guide

Content

Introduction

The Social Security Administration (SSA), in partnership with the Office of Management and Budget, as well as the Department of Treasury, is implementing ways to give Americans machine-readable access to personal information maintained by the federal government as part of the MyData Finance Initiative. In addition to facilitating secure and consent-based sharing of information with trusted third parties, the policy objectives of MyData finance are to:

  • Give people more control over their personal financial information so they can make better decisions
  • Use technology to provide new government and private-sector services that are useful to people and that will stimulate positive economic activity
  • Improve customer satisfaction with the public’s interaction with the government
  • Unleash innovation in the private sector that will lead to social and economic benefits

Back to Index

Overview

The my Social Security provides users immediate access to their earnings record, benefit estimates, and other information. They can also download an eXtensible Markup Language (XML) version of the statement data. Users must have a valid my Social Security account to access their information via https://www.ssa.gov/myaccount/. The eligible user selects to download their Social Security Statement data, and the application transforms the user’s data into XML. The resulting XML file is transmitted back to the user’s browser as a file download.

Back to Index

XML Schema Definition (XSD)

The Online Social Security Statement furnishes an accompanying XML schema definition (XSD). This schema is intended to be used by third party developers who plan to create software systems that utilize Statement data. This schema provides metadata about the format of the Statement XML data. This schema is maintained by Social Security.

Schema URL: Your_Social_Security_Statement.xsd

Schema Data Elements

Back to Index

Description Of Data Elements

The following data elements will be included in the XML file

Element Description Value Required? Value Example
OnlineSocialSecurityStatementData Structure containing the user's Online Social Security Statement Data. It contains the FileCreationDate,
UserInformation, EstimatedBenefits, andEarningsRecord elements.		 Not Applicable Not Applicable Not Applicable
FileCreationDate The date that the file was created. Required CCYY-MM-DDThh:mm:ss.sss[Z|(+|-)hh:mm 2015-05-19T08:52:10.055-04:00
UserInformation Structure containing the user's biographical information. It contains the Name and DateOfBirth elements. Not Applicable Not Applicable Not Applicable
Name The user’s name formatted to be displayed with the First Name with the 1st initial capitalized,
the Middle Initial capitalized with a period after it (if provided), and the Last Name with the 1st initial capitalized.		 Required String John Q. Public
DateOfBirth The user’s date of birth. Required CCYY-MM-DD 1980-09-21
EstimatedBenefits Structure containing the user's Benefit Estimates. Not Applicable Not Applicable Not Applicable
EarlyRetirementEstimate Not Applicable Not Applicable Not Applicable
RetirementAge It contains the Years element. Not Applicable Not Applicable Not Applicable
Years The year of the user’s early retirement age. Optional1 Integer 64
Months The month of the early retirement age Optional3 Integer 2
Estimate The estimated early retirement benefit to be received if the user retires at the
accompanying early retirement age		 Optional1 Integer 2290
FullRetirementEstimate Not Applicable Not Applicable Not Applicable
RetirementAge The Years element will always be included. The Months element will only be included when it is displayed to the user. Not Applicable Not Applicable Not Applicable
Years The year of the user’s early retirement age. Optional2 Integer 66
Months The month of the full retirement age Optional3 Integer 2
Estimate The estimated full retirement benefit to be received if the user retires at the accompanying full retirement age Optional2 Integer 2498
DelayedRetirementEstimate Not Applicable Not Applicable Not Applicable
RetirementAge It contains the Years element. Not Applicable Not Applicable Not Applicable
Years The year of the user’s delayed retirement age. Optional4 Integer 66
Months The month of the delayed retirement age Optional3 Integer 2
Estimate The estimated delayed retirement benefit to be received if the user retires at the accompanying delayed retirement age Optional4 Integer 2498
Age62RetirementEstimate The estimated benefit to be received if the user retires at age 62 Not Applicable Not Applicable Not Applicable
Age63RetirementEstimate The estimated benefit to be received if the user retires at age 63 Not Applicable Not Applicable Not Applicable
Age64RetirementEstimate The estimated benefit to be received if the user retires at age 64 Not Applicable Not Applicable Not Applicable
Age65RetirementEstimate The estimated benefit to be received if the user retires at age 65 Not Applicable Not Applicable Not Applicable
Age66RetirementEstimate The estimated benefit to be received if the user retires at age 66 Not Applicable Not Applicable Not Applicable
Age67RetirementEstimate The estimated benefit to be received if the user retires at age 67 Not Applicable Not Applicable Not Applicable
Age68RetirementEstimate The estimated benefit to be received if the user retires at age 68 Not Applicable Not Applicable Not Applicable
Age69RetirementEstimate The estimated benefit to be received if the user retires at age 69 Not Applicable Not Applicable Not Applicable
Age70RetirementEstimate The estimated benefit to be received if the user retires at age 70 Not Applicable Not Applicable Not Applicable
DisabilityEstimate The estimated disability benefit to be received if the user becomes disabled right now. Optional5 Integer 2498
OneTimeDeathBenefit The amount of the one-time death benefit that the user’s spouse or child may be eligible for. Optional 6 Integer 255
SurvivorsEstimateChild The estimated survivors benefit amount that the user’s child may be eligible for. Optional 6 Integer 1873
SurvivorsEstimateFamily The estimated maximum amount of survivors benefits that the user’s family may be eligible for. Optional 6 Integer 4372
SurvivorsEstimateRetired The estimated survivors benefit amount that the user’s spouse may receive starting at full retirement age. Optional 7 Integer 2498
SurvivorsEstimateSpouseChild The estimated survivors benefit amount that the user’s spouse who is caring for the user’s child may be eligible for. Optional 6 Integer 1873
EarningsRecord Structure containing the user's Earnings, FICA and Medicare taxes paid. It contains the Earnings,
FicaTaxTotalEmployer, FicaTaxTotalIndividual, MedicareTaxTotalEmployer, and MedicareTaxTotalIndividual elements.		 Not Applicable Not Applicable Not Applicable
Earnings Structure containing the user’s yearly earnings information.
It has the endYear and startYear attributes. It contains the FicaEarnings and MedicareEarnings elements.		 Not Applicable Not Applicable Not Applicable
startYear The start year of the time period (Work Year) that the accompanying earnings will pertain to. Required CCYY 1937
endYear The end year of the time period (Work Year) that the accompanying earnings will pertain to. Required CCYY 1950
FicaEarnings The amount of Social Security Taxed Earnings in the time period (Work Year).
Note: If the year prior to the current year does not have a value, “-1” will be included to represent “Not yet recorded”.		 Required Integer 106800
MedicareEarnings The amount of Medicare Taxed Earnings in the time period (Work Year).
Note: The 1st year of Medicare taxes was 1966. For years prior to 1966, the value will be provided as “0”. If the year prior to the current year does not
have a value, “-1” will be included to represent “Not yet recorded”.		 Required Integer 157913
FicaTaxTotalEmployer The estimated total Social Security taxes paid by the employer. Required Integer 121467
FicaTaxTotalIndividual The estimated total Social Security taxes paid by the employer. Required Integer 121292
MedicareTaxTotalEmployer The estimated total Medicare taxes paid by the employer Required Integer 34436
MedicareTaxTotalIndividual The estimated total Medicare taxes paid by the user. Required Integer 34422

Data Element Footnotes

1 - The element will be blank if the individual is already receiving benefits, is not retirement insured, or is too old to receive an early retirement estimate.
2 - The element will be blank if the individual is already receiving benefits, is not retirement insured, or is too old to receive a full retirement estimate.
3 - The element will be blank if the individual is already receiving benefits, is not retirement insured, is too old to receive a full retirement estimate, or full retirement age does not include months.
4 - The element will be blank if the individual is already receiving benefits, or is not retirement insured.
5 - The element will be blank if the individual is already receiving benefits, is not disability insured, or is old enough to apply for retirement so they are not eligible for disability.
6 - The element will be blank if the individual is already receiving benefits, or is not survivors insured and has not earned enough recent quarters of credit in order for his or her spouse to receive survivors benefits at retirement age.
7 - The element will be blank if the individual is already receiving benefits, is not survivors insured, or has not earned enough recent quarters of credit in order for his or her spouse to receive survivors benefits at retirement age.

Back to Index

Sample XML Data

This section includes XML samples of the data contained in different Statement benefit estimate categories.

Category Description XSD Sample
Early Retirement This sample shows the requestor is eligible to receive estimates and is younger than the early retirement age Early_Retirement.xml
Full Retirement This sample shows the requestor is eligible to receive estimates and has reached their full retirement age Full_Retirement.xml
Delayed Retirement This sample shows the requestor is eligible to receive estimates and has reached their delayed retirement age Delayed_Retirement.xml
Not enough Coverage This sample shows the requestor does not have enough quarters of coverage to receive estimates Not_Enough_Credits.xml

Back to Index

Acronyms

Acronym Acronym Definition
DD Day of Birth
DOB Date of Birth
MM Month of Birth
SSA Social Security Administration
SSN Social Security Number
XML eXtensible Markup Language
XSD XML Schema Definition
YYYY Year of Birth

Back to Index

Revision History

Version Date Reason for Change
1.0 06/05/2015 Initial draft
2.0 09/18/2021 Added more retirement estimates

Back to Index