From CVRG Wiki

Welcome to the user guide for the Social Security Death Master File User Interface, an online tool for searching and retrieving Death Index information.

Contents 1 SSDMF User Interface Description 2 System Requirements 3 QUICK START GUIDE 4 ECGrid Toolkit Workflow 4.1 Login 4.1.1 Demo Login Account 4.1.2 Live Login Account 4.1.3 Successful Login 4.2 Logout 4.3 Finding People in SSDMF 4.3.1 Find Person 4.3.2 Find Many 4.3.3 Result Storage 4.4 View Query Results 4.4.1 Get Information 4.4.1.1 Results File Example 4.4.1.1.1 SSDMF Results Fields 5 IT Staff: Obtaining ECGrid Toolkit Source Code and Hosting the ECGrid Toolkit on Your Own

SSDMF User Interface Description

The Social Security Death Master File User Interface(SSDMF-UI) is an online tool provides an easy to use web page for querying the Social Security Administration's list of deceased people. SSDMF-UI enables users to log into the SSDMF, query it and download the results in a spreadsheet friendly "CSV" format.

The only software needed to access the Service is a standard Web browser. However, you may wish to use certain software applications on your local machine to read the result files. You must purchase a SSDMF account from the Social Security Administration, the user ID and password they provide is used to log into the SSDMF-UI web page, which validates your account with the SSDMF's web services. (Login)

Users can enter a person's first and last names and date of birth, and SSDMF-UI gets the latest matching entry(s) from the SSDMF web service and stores them in a Comma Separated Value (CSV) file which can downloaded at any time and viewed in a standard spreadsheet program. (more on this procedure below).

Users can alternatively upload a list of names and dates of birth. All of the names will be looked up in the SSDMF web service and all of the results will be stored in single CSV file. (more on this procedure below).

System Requirements

The ECGrid Toolkit works best with the following software:

Software Type	Vendor/Name	Recommended Version
Operating System	Windows	XP, Vista & 7
	Mac OSX	10.5.8
Web Browser	Google Chrome	14
	Apple Safari	5.0.6 & 5.1
	Opera	11.51
	Microsoft Internet Explorer	6, 7, 8 & 9
	Mozilla Firefox	3.6, 6.0.2 & 7.0
Runtime Environment	Java	6.0

Visit the Java download page to download and install a version of Java 6.0.

QUICK START GUIDE

Logging in:

1. Open this link SSDMF-UI in a web browser.
2. Enter User ID and Password (e.g. “demo” & “demo”)
3. View CVRG SSDMF Terms of Use agreement.
4. Check the check box if you agree to the terms of use.
5. Click the “Connect to SSDMF” button.

Searching for a single person in SSDMF, after logging in:

1. Click the “Find Person” menu tab.
2. Enter the person’s first name, last name and date of birth. (e.g. “Wile”, “Coyote”, “9/17/1949”)
3. Click the “Lookup One Person” button.
4. Select the matching result from the displayed list on the “Get Information” menu tab. (e.g. WileCoyote09-17-1949)
5. Open the downloaded file in your favorite spreadsheet program.

Searching for a list of people in SSDMF, after logging in:

1. Click the “Find Many” menu tab.
2. Create a list of people as a .csv text file (e.g. “ThreeJohnSmiths.csv”) on your local computer, following the format prescribed on this tab.
3. Click the “Browse” button and select this file.
4. Click the “Find Many” button.
5. Select the matching result from the displayed list on the “Get Information” menu tab. (e.g. ThreeJohnSmiths)
6. Open the downloaded file in your favorite spreadsheet program.

Logging out (there is no automatic timed logout):

1. Click the “Disconnect” menu tab.

ECGrid Toolkit Workflow

Login

The first thing you will see when accessing the ECGrid Toolkit is the login page.

To Log In, enter your User Name and Password and click the Connect to SSDMF button.

Demo Login Account

If you don't have a user name, you may login with both the user name of "demo" and password of "demo" to try the system out.
The demo account does not connect to SSDMF, but instead returns simulated SSDMF style data.
Normally the simulated result is constructed from the Name and DOB you entered and with a random DOD between 2008 and 2012.
The Middle name, State and Zip for single lines will be "DEMO_Middle_Name_DEMO", "Maryland" and "21218" respectively.

In the special case of "John Smith" with the birth date(DOB) of "04021885", the demo account will return TWO fiction people named "John Smith" both with the same birth date(DOB) of 04-02-1885.
This illustrates how SSDMF responds if a query does not uniquely identify an individual.
In a real query, the first name, last name, DOB data are frequently sufficient to identify a single person, in which case only a single row of data will be return.
For the demo account, the SSN are always one of the two "reserved/invalid SSNs for use in advertising" numbers.

Live Login Account

Please read this pdf from the SSA for information on purchasing a user name and password.
This is required to lookup actual SSDMF data.

Successful Login

If the connection is successful, a list of Usage Instruction links (to this Wiki) should appear.
Above the Usage Instructions are menu tabs, clicking these will take you to the other functions of SSDMF-UI.

Logout

To Log out, click the Disconnect menu tab. This will:

1. Disconnect the browser from SSDMF-UI.
2. Prevent unauthorized people from accessing your results from the current browser session.
3. Halt and reset any lookups currently in progress from this browser, including frozen lookups.

Finding People in SSDMF

Find Person

1. Click the “Find Person” menu tab.
2. Enter the person’s first name, last name and date of birth. (e.g. “Wile”, “Coyote”, “9/17/1949”)
3. Click the “Lookup One Person” button.
4. Select the matching result from the displayed list on the "Get Information" menu tab. (e.g. WileCoyote09-17-1949)
5. Open the downloaded file in your favorite spreadsheet program.

This page lets you query the SSDMF regarding a single Name and DOB combination. (note: this may return multiple answers if the name was popular that year.)
If the SSDMF does not find any matches, then this UI will generate a single line place-keeper response(in the SSDM format) containing just the first name, last name and DOB entered. The Date of Death (DOD) and all other columns in the place-keeper response will be left blank to indicate that the values where not found.

You can download the query results in .CSV format in the Get Information tab. For details, see the section on Get Information below.

Find Many

1. Click the “Find Many” menu tab.
2. Create a list of people as a .csv text file (e.g. “ThreeJohnSmiths.csv”) on your local computer, following the format prescribed on this tab.
3. Click the “Browse” button and select this file.
4. Click the “Find Many” button.
5. Select the matching result from the displayed list on the “Get Information” menu tab. (e.g. ThreeJohnSmiths)
6. Open the downloaded file in your favorite spreadsheet program.

This page lets you query the SSDMF regarding a list of Name and DOB combinations. (note: this may return multiple answers per name if the name was popular that year.)
If the SSDMF does not find any matches for a person in the list, then this UI will add a single line place-keeper to the output file as described in Find Person above.
The results for querying the entire list will be placed in a single .CSV file with the same name as the list file.
You can download the results at the Get Information tab. For details, see the section on Get Information below.
The list is a .CSV file, in a specific format, which is uploaded on this page. Here is a Find Many List sample.
The required list format is as follows:

1. It is a Comma Separated Value (.csv) file containing a list of people to look up in the SSDMF.
2. Each line of the file should contain three columns in the form: Firstname,Lastname,Date of Birth
• The first and last names must be spelled correctly e.g. "Jon,Smith" will not match "John,Smith"
• The first and last names are NOT case sensitive e.g. "bob" and "BOB" and "Bob" will all match "Bob"
• Compounded last names must match completely e.g. "Valez-Russell" will not match "Valez Russell" or "Valez/Russell"
• The date can be in the following formats: mm/dd/yyyy or mm,dd,cc,yy or "mm,dd,cc,yy"

The procedure is:

1. Create a list file on your local machine, giving it a unique name with extension ".csv".
2. Click the "Browse" button and select you list file.
3. Click the "Find Many" button
4. After the list is processed, the "Get Information" tab will be displayed. The Result ID list will now contain an entry which matches the name of your list file.

Note:If a list file is processed a 2nd time (or another file with the same name), the new results will overwrite the previous results.

Result Storage

The SSDMF query results files are stored on the JHU server by default.
The results are available for many weeks, but are not guaranteed to be kept long term. You should download your results promptly.
The source code of the SSDMF-UI can be reconfigured to send the output files to another destination.
Please contact us for support changing the destination of the output files.

View Query Results

Get Information

The results of every query run by this user ID will be listed in the Get Information tab.

1. Click the “Get Information” menu tab.
2. Click the checkbox next to the Result ID you wish to see. (e.g. WileCoyote09-17-1949)
3. It will immediately try to download the .csv result file.
• If your have Excel installed in Microsoft's default manner, the result will open in Excel.
• Some browsers will offer to save the file for you.
• Some browsers will open the result in you current window, forcing you out of the SSDMF-UI.

The Find Person input fields are used to generate the Result ID and the file name of the CSV results file so that they can be easily identified.
The Result ID will be in the form FNameLNameDOB (e.g. JonathanCranberry05-05-1960) and the file name will be in the form SSDMFResultFNameLNameDOB.csv for Find Person.
The downloaded file will be a csv file such as below containing all the matches for a single name and DOB entered in Find Person tab.
If the same name and DOB are entered again, the SSDMF will be queried for the latest data and it will replace the current file.

For Find Multiple the Result ID will be in the name of the uploaded list and the result file name will be in the form SSDMFResultUploadFilename.csv
The downloaded file will contain all of the matches for all of the people listed in the uploaded list.
If a list with same filename is uploaded again, the SSDMF will be queried for the latest data and it will replace the current file even if different people are listed.

Results File Example

Above is illustrated the fictitious Find Person result generated by the demo account when opened using Microsoft Excel 2007.
Here is the actual sample result file.

In row 1, the column headers A through P are the same as the data fields returned by the SSDMF web service. Rows 2 and 3 illustrate the type of data returned if the query identifies more than one dead person. (John Smith 05-09-19-1891) There are several anomalies to note: 1. The DOD in cell J2 was actually returned by the SSDMF web service but it is not a valid date so Excel displays the raw text. This type of error is in SSA database so the UI can only pass it on to the result file. 2. The DOD in cell J3 is a valid date, so Excel converted it to its internal date format. 3. The DOBs in cell K2 and K3 are valid dates but this version of Excel doesn't recognize dates before 1900, so it displays the raw text. 4. The header in column O is misspelled to match the misspelled field name which the SSDMF web service generates.

The demo account will generate the above fictitious response file regardless of what is entered in the Name and DOB fields.
A real User ID will of course contain the real results returned by the SSDMF web service.

SSDMF Results Fields

The headers in the result file are exactly the same as the field names returned by the SSDMF. I have not found where these fields are documented, below are my best interpretation of their meanings.

Field	Description
diffgr:id	Line identifier for a single query's results, starts with SSN1 and increases SSN2, SSN3 etc. if more than one line is returned by a query.
msdata:rowOrder	A zero based integer, increases by one on successive lines if more than one line is returned by a query.
Status	unknown, this has been blank on all my tests.
SSN	Social Security Number of the deceased person.
LastName	Last Name of the deceased person, e.g. "Smith".
SuffixName	Title Suffix of of the deceased person, e.g "Jr.", "Dr.", "Esq.".
FirstName	First Name of the deceased person, e.g. "Smith".
MiddleName	Middle Name of the deceased person, e.g. "Quincy".
VPCode	unknown, this has been blank on all my tests.
DOD	Date of Death of the deceased person, in the form MM-DD-YYYY.
DOB	Date of Birth of the deceased person, in the form MM-DD-YYYY.
State	Perhaps State name where death was recorded, e.g. "Maryland" but this has been blank on all my tests.
ZipLastRes	Perhaps US Postal Code of the deceased last residence, e.g. "21218" but this has been blank on all my tests.
ZipLumpSum	unknown, this has been blank on all my tests.
siganture_date	Time that the query was executed in the form YYYY-MM-DDTHH:MM:SS.sss-UTC offset, e.g. "2011-12-12T15:05:26.547-05:00"
URL	unknown, this has been blank on all my tests.

IT Staff: Obtaining ECGrid Toolkit Source Code and Hosting the ECGrid Toolkit on Your Own

IT staff and administrators: Click here for instructions on how to obtain the ECGrid Toolkit source code and/or deploy and host the ECGrid Toolkit on your organization's web server.